@drakkar.software/starfish-client 3.0.0-alpha.10 → 3.0.0-alpha.12

package/dist/append-log.d.ts

@@ -1,4 +1,4 @@
-import { type Alg, type Encryptor } from "@drakkar.software/starfish-protocol";
+import { type Encryptor } from "@drakkar.software/starfish-protocol";
 import type { StarfishClient } from "./client.js";
 import type { SyncLogger } from "./logger.js";
 /**
@@ -28,8 +28,6 @@ export interface AuthorVerifier {
      *  (verify only that the signature is valid for the element's self-declared
      *  `authorPubkey` — see the `verifyAuthor` note on restricting authors). */
     expectedAuthorPubkey?: string;
-    /** Signing suite the signatures were produced under. Defaults to `DEFAULT_ALG`. */
-    alg?: Alg;
 }
 /**
  * What to do when a single element fails verification or decryption during a

package/dist/append-log.js

@@ -0,0 +1,267 @@
+import { verifyAppendAuthor, } from "@drakkar.software/starfish-protocol";
+/** The `/pull/` action prefix; mirrors `PUSH_PATH_PREFIX` for the read side. */
+const PULL_PATH_PREFIX = "/pull/";
+/** The storage `documentKey` for a pull `path`: the path with the `/pull/`
+ *  action prefix stripped (the namespace lives only in the URL). The author
+ *  signature binds to this key, so a reader re-derives it the same way the
+ *  writer did from `/push/…`. */
+function stripPullPrefix(path) {
+    return path.startsWith(PULL_PATH_PREFIX) ? path.slice(PULL_PATH_PREFIX.length) : path;
+}
+/** Thrown when an append element's author signature fails verification. */
+export class AppendAuthorError extends Error {
+    ts;
+    constructor(ts) {
+        super(`append element author verification failed (ts=${ts})`);
+        this.ts = ts;
+        this.name = "AppendAuthorError";
+    }
+}
+/** Largest `ts` among `items`, or `0` when empty. The checkpoint for an
+ *  append-only log is exactly this — the server returns elements with
+ *  `ts > checkpoint`, and element timestamps are strictly increasing. */
+export function checkpointOf(items) {
+    let max = 0;
+    for (const it of items)
+        if (it.ts > max)
+            max = it.ts;
+    return max;
+}
+/** Copy the optional author fields from `src` onto a fresh element with `data`. */
+function withAuthor(ts, data, src) {
+    const out = { ts, data };
+    if (src.authorPubkey !== undefined)
+        out.authorPubkey = src.authorPubkey;
+    if (src.authorSignature !== undefined)
+        out.authorSignature = src.authorSignature;
+    return out;
+}
+/**
+ * A stateful cursor over an append-only collection. It owns the accumulated
+ * array of elements and pulls only what is new: each {@link pull} derives the
+ * checkpoint from the last element it holds and asks the server for elements
+ * with a greater `ts`.
+ *
+ * This is the incremental, stateful counterpart to the deliberately stateless
+ * `client.pull(path, { appendField, since })`, and the sibling of
+ * {@link SyncManager} for append-only logs (no merge / push-conflict
+ * machinery — a log only grows).
+ *
+ * The cursor accumulates every pulled element in memory; for an unboundedly
+ * large log, pull a bounded window with raw `client.pull(path, { last })` instead.
+ *
+ * Cold start (nothing persisted) — first `pull()` fetches the whole collection:
+ * ```ts
+ * const log = new AppendLogCursor({ client, pullPath: "/pull/events" })
+ * const all = await log.pull()
+ * ```
+ * Warm start (resume from persisted data) — first `pull()` fetches only newer
+ * elements; persistence is a round-trip of `getItems()`:
+ * ```ts
+ * const log = new AppendLogCursor({ client, pullPath: "/pull/events",
+ *   initialItems: await store.load() })
+ * const fresh = await log.pull()
+ * await store.save(log.getItems())
+ * ```
+ * Warm start for an **E2EE** log — persist ciphertext, render decrypted:
+ * ```ts
+ * const log = new AppendLogCursor({ client, pullPath: "/pull/streamchat",
+ *   encryptor, persistEncrypted: true, onElementError: "skip",
+ *   initialItems: await store.load() })           // ciphertext from disk
+ * const history = await log.getDecryptedItems()    // render persisted history
+ * const fresh = await log.pull()                   // decrypted delta
+ * await store.save(log.getItems())                 // ciphertext back to disk
+ * ```
+ */
+export class AppendLogCursor {
+    client;
+    pullPath;
+    appendField;
+    encryptor;
+    verifyAuthor;
+    onElementError;
+    persistEncrypted;
+    documentKey;
+    logger;
+    loggerName;
+    items;
+    lastCheckpoint;
+    /** Tail of the serialized pull chain. Concurrent `pull()` calls queue behind
+     *  it so each runs against the checkpoint the previous one advanced — no two
+     *  overlapping fetches read the same checkpoint and double-append a window. */
+    pullChain = Promise.resolve();
+    constructor(options) {
+        this.client = options.client;
+        this.pullPath = options.pullPath;
+        this.appendField = options.appendField ?? "items";
+        this.encryptor = options.encryptor;
+        this.verifyAuthor = options.verifyAuthor;
+        this.onElementError = options.onElementError ?? "throw";
+        this.persistEncrypted = options.persistEncrypted ?? false;
+        this.documentKey = stripPullPrefix(options.pullPath);
+        this.logger = options.logger;
+        this.loggerName =
+            options.loggerName ?? options.pullPath.split("/").filter(Boolean).pop() ?? options.pullPath;
+        const seed = options.initialItems ?? [];
+        const seedCheckpoint = checkpointOf(seed);
+        if (options.since != null) {
+            if (options.since < 0)
+                throw new Error("since must be non-negative");
+            if (options.since < seedCheckpoint) {
+                throw new Error("since must be >= the max ts of initialItems");
+            }
+            this.lastCheckpoint = options.since;
+        }
+        else {
+            this.lastCheckpoint = seedCheckpoint;
+        }
+        this.items = [...seed];
+    }
+    /**
+     * Fetch elements newer than the current checkpoint, verify + decrypt them,
+     * append them to the local log, and return ONLY the newly-fetched batch
+     * (decrypted when an `encryptor` is set).
+     *
+     * Atomic under `onElementError: "throw"` (the default): the batch is fully
+     * verified and decrypted into a local before any state mutation, so a
+     * verify/decrypt failure throws without advancing the checkpoint past elements
+     * that could never be re-fetched. Under `"skip"`, a failing element is dropped
+     * from the returned batch but the checkpoint still advances past it.
+     *
+     * Safe to call concurrently: overlapping calls are serialized internally, so
+     * each runs against the checkpoint the previous one advanced (no double-fetch
+     * of the same window). The next pull after one completes will pick up anything
+     * that arrived in between.
+     */
+    async pull() {
+        // Chain onto the previous pull (whether it resolved or rejected) so calls
+        // run one-at-a-time against the latest checkpoint. `pullChain` swallows
+        // outcomes to stay alive; the caller still sees this call's real result.
+        const run = this.pullChain.then(() => this.doPull(), () => this.doPull());
+        this.pullChain = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    async doPull() {
+        this.logger?.pullStart(this.loggerName);
+        const start = performance.now();
+        try {
+            const since = this.lastCheckpoint;
+            // Omit `since` on cold start so the request carries no `?checkpoint=`.
+            const opts = since > 0 ? { appendField: this.appendField, since } : { appendField: this.appendField };
+            const raw = await this.client.pull(this.pullPath, opts);
+            const batch = []; // decrypted, returned to the caller
+            const stored = []; // what we keep in `items` (cipher- or plaintext)
+            let maxTs = since;
+            let skipped = 0;
+            for (const el of raw) {
+                // Defensive: guard a misbehaving/mocked server from making us
+                // double-append a held element. Gated on `since > 0` to mirror the
+                // server (which only filters when checkpoint > 0): on a cold start
+                // `since` is 0 and we must NOT drop a legitimate `ts: 0` first element.
+                if (since > 0 && el.ts <= since)
+                    continue;
+                // Advance past every windowed element BEFORE verify/decrypt so a skipped
+                // element still moves the checkpoint and is never re-fetched.
+                if (el.ts > maxTs)
+                    maxTs = el.ts;
+                let decrypted = null;
+                try {
+                    this.verifyOne(el);
+                    const data = this.encryptor ? await this.encryptor.decrypt(el.data) : el.data;
+                    decrypted = withAuthor(el.ts, data, el);
+                }
+                catch (err) {
+                    // "throw" rethrows here, before any state mutation below — atomic.
+                    if (this.onElementError !== "skip")
+                        throw err;
+                    skipped++;
+                }
+                if (this.persistEncrypted) {
+                    // Keep the original ciphertext envelope (even for a skipped element:
+                    // it is valid data we simply cannot read now — a later key might).
+                    stored.push(withAuthor(el.ts, el.data, el));
+                }
+                else if (decrypted) {
+                    stored.push(decrypted);
+                }
+                if (decrypted)
+                    batch.push(decrypted);
+            }
+            this.items.push(...stored);
+            this.lastCheckpoint = maxTs;
+            this.logger?.pullSuccess(this.loggerName, Math.round(performance.now() - start), skipped > 0 ? { skippedCount: skipped } : undefined);
+            return batch;
+        }
+        catch (err) {
+            this.logger?.pullError(this.loggerName, err instanceof Error ? err.message : String(err));
+            throw err;
+        }
+    }
+    /** Verify a single element's author signature over its RAW (pre-decryption)
+     *  `data`. Throws {@link AppendAuthorError} on any failure. No-op when
+     *  verification is disabled. */
+    verifyOne(el) {
+        if (!this.verifyAuthor)
+            return;
+        const policy = typeof this.verifyAuthor === "object" ? this.verifyAuthor : {};
+        const { authorPubkey, authorSignature } = el;
+        if (!authorPubkey || !authorSignature)
+            throw new AppendAuthorError(el.ts);
+        // Public keys are hex, which is case-insensitive — compare normalized so a
+        // caller passing a differently-cased `expectedAuthorPubkey` isn't falsely rejected.
+        if (policy.expectedAuthorPubkey &&
+            authorPubkey.toLowerCase() !== policy.expectedAuthorPubkey.toLowerCase()) {
+            throw new AppendAuthorError(el.ts);
+        }
+        void policy;
+        const ok = verifyAppendAuthor(this.documentKey, el.data, authorPubkey, authorSignature);
+        if (!ok)
+            throw new AppendAuthorError(el.ts);
+    }
+    /** The full accumulated log (a shallow copy), in `ts` order. Under
+     *  `persistEncrypted` these carry CIPHERTEXT `data` (persist them as-is, then
+     *  re-seed via `initialItems`); otherwise they carry decrypted/plaintext data. */
+    getItems() {
+        return [...this.items];
+    }
+    /**
+     * The full accumulated log, DECRYPTED — for rendering warm-started history in
+     * `persistEncrypted` mode (where {@link getItems} holds ciphertext). Honors
+     * `onElementError` (a `"skip"` cursor drops elements it cannot read). When the
+     * cursor has no `encryptor`, or is not in `persistEncrypted` mode, the held
+     * elements are already plaintext/decrypted and are returned as-is.
+     */
+    async getDecryptedItems() {
+        const snapshot = [...this.items];
+        if (!this.encryptor || !this.persistEncrypted)
+            return snapshot;
+        const out = [];
+        for (const el of snapshot) {
+            try {
+                this.verifyOne(el);
+                const data = await this.encryptor.decrypt(el.data);
+                out.push(withAuthor(el.ts, data, el));
+            }
+            catch (err) {
+                if (this.onElementError !== "skip")
+                    throw err;
+            }
+        }
+        return out;
+    }
+    /** The current checkpoint: the max `ts` held (the next pull's `since`). `0`
+     *  when nothing has been pulled or seeded. */
+    getCheckpoint() {
+        return this.lastCheckpoint;
+    }
+    /** Restore the checkpoint without seeding items — for persistence layers that
+     *  store only the checkpoint. Used to resume incrementally across restarts.
+     *  Rejects a value below the max `ts` already held: rewinding would make the
+     *  next pull re-deliver, and duplicate, elements the cursor already has. */
+    setCheckpoint(ts) {
+        if (ts < checkpointOf(this.items)) {
+            throw new Error("checkpoint must be >= the max ts already held");
+        }
+        this.lastCheckpoint = ts;
+    }
+}

package/dist/background-sync.js

@@ -0,0 +1,29 @@
+/**
+ * Background Sync API integration for pending changes.
+ * Uses the Web Background Sync API to retry failed sync operations
+ * when connectivity is restored, even if the app is closed.
+ */
+/** Check if the Background Sync API is supported in the current environment. */
+export function isBackgroundSyncSupported() {
+    return (typeof navigator !== "undefined" &&
+        "serviceWorker" in navigator &&
+        "SyncManager" in globalThis);
+}
+/**
+ * Register a background sync event with the active service worker.
+ * Returns true if registration succeeded, false if not supported or no active SW.
+ */
+export async function registerBackgroundSync(opts) {
+    if (!isBackgroundSyncSupported())
+        return false;
+    const tag = opts?.tag ?? "starfish-sync";
+    try {
+        const registration = await navigator.serviceWorker.ready;
+        // @ts-expect-error - SyncManager types may not be available
+        await registration.sync.register(tag);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/bindings/suspense.js

@@ -0,0 +1,49 @@
+/**
+ * React Suspense integration for Starfish sync data.
+ * Creates resources that throw Promises while loading (Suspense protocol).
+ */
+/**
+ * Create a Suspense-compatible resource from an async fetcher.
+ * The first call to `read()` triggers the fetch. While loading, `read()` throws
+ * a Promise (which React Suspense catches to show a fallback). Once resolved,
+ * `read()` returns the value synchronously.
+ *
+ * @example
+ * ```tsx
+ * const resource = createSuspenseResource(() => syncManager.pull())
+ * function MyComponent() {
+ *   const data = resource.read() // throws while loading, returns data when ready
+ *   return <div>{JSON.stringify(data)}</div>
+ * }
+ * ```
+ */
+export function createSuspenseResource(fetcher) {
+    let status = "pending";
+    let result;
+    let error;
+    let promise = null;
+    function init() {
+        if (promise)
+            return promise;
+        promise = fetcher().then((value) => {
+            status = "resolved";
+            result = value;
+        }, (err) => {
+            status = "rejected";
+            error = err;
+        });
+        return promise;
+    }
+    return {
+        read() {
+            switch (status) {
+                case "pending":
+                    throw init();
+                case "resolved":
+                    return result;
+                case "rejected":
+                    throw error;
+            }
+        },
+    };
+}

package/dist/bindings/zustand.js

@@ -240,11 +240,9 @@ import {
   HEADER_SIG,
   HEADER_TS,
   HEADER_NONCE,
-  HEADER_ALG,
   HEADER_PUB,
   HEADER_CONTENT_TYPE,
   HEADER_ACCEPT,
-  DEFAULT_ALG,
   signAppendAuthor,
   signRequest,
   stableStringify
@@ -354,23 +352,19 @@ var StarfishClient = class {
    * presenter` bind the server checks.
    */
   async capRequestHeaders(capCtx, method, pathAndQuery, body) {
-    const { cap, devEdPrivHex, pubHex, presenterAlg } = capCtx;
+    const { cap, devEdPrivHex, pubHex } = capCtx;
     const req = {
       method,
       pathAndQuery,
       body,
       host: this.signingHost()
     };
-    const signAlg = cap.kind === "audience" ? presenterAlg ?? DEFAULT_ALG : cap.subAlg ?? cap.issAlg;
-    const { alg, sig, ts, nonce } = await signRequest(req, devEdPrivHex, {
-      alg: signAlg
-    });
+    const { sig, ts, nonce } = await signRequest(req, devEdPrivHex);
     const headers = {
       [HEADER_AUTHORIZATION]: `Cap ${encodeCapAuth(cap)}`,
       [HEADER_SIG]: sig,
       [HEADER_TS]: String(ts),
-      [HEADER_NONCE]: nonce,
-      [HEADER_ALG]: alg
+      [HEADER_NONCE]: nonce
     };
     if (pubHex !== void 0) headers[HEADER_PUB] = pubHex;
     return headers;
@@ -384,11 +378,10 @@ var StarfishClient = class {
    * unsigned and a server requiring signatures rejects it.
    */
   appendAuthorKey(capCtx) {
-    const { cap, pubHex, presenterAlg } = capCtx;
+    const { cap, pubHex } = capCtx;
     const authorPubHex = pubHex ?? cap.sub;
     if (authorPubHex === void 0) return null;
-    const signAlg = cap.kind === "audience" ? presenterAlg ?? DEFAULT_ALG : cap.subAlg ?? cap.issAlg;
-    return { authorPubHex, signAlg };
+    return { authorPubHex };
   }
   async pull(path, checkpointOrOptions) {
     let pathAndQuery = this.applyNamespace(path);
@@ -436,12 +429,16 @@ var StarfishClient = class {
     return result;
   }
   /**
-   * Pull several collections in one round-trip via `/batch/pull`. `collections`
-   * is the list of collection names; `opts.params` supplies path params per
-   * collection (serialized to a URL-encoded JSON `params` query). The server
-   * auto-fills the `{identity}` param from the authenticated caller, so per-user
-   * collections need no params. Returns a map of collection name → its pulled
-   * document or a per-collection `{ error }`. Honors the configured namespace.
+   * Pull several documents in one round-trip via `/batch/pull`. `collections` is
+   * the list of distinct collection names; `opts.params` supplies, per collection,
+   * an ARRAY of path-param sets — one per document to read — so the SAME collection
+   * can fan in many documents (e.g. many users' `profile`) in a single request.
+   * The server auto-fills the `{identity}` param from the authenticated caller for
+   * any set that omits it, so a self-doc collection needs no params. Returns a map
+   * of collection name → an ARRAY of pulled documents (or per-document `{ error }`),
+   * in request order. Honors the configured namespace.
+   *
+   * For the common "many docs of one collection" case prefer {@link batchPullMany}.
    *
    * Note: not append/checkpoint-aware — for incremental append-only reads use
    * `pull(path, { since })` (or `AppendLogCursor`) per collection.
@@ -464,6 +461,18 @@ var StarfishClient = class {
     }
     return await res.json();
   }
+  /**
+   * Convenience over {@link batchPull} for reading MANY documents of ONE
+   * collection in a single round-trip: pass the per-document param-sets and get
+   * back the {@link BatchPullEntry} array aligned to `paramsList` by index (each
+   * entry is `{ data, hash, timestamp }` or `{ error }`). An empty `paramsList`
+   * issues no request and returns `[]`.
+   */
+  async batchPullMany(collection, paramsList) {
+    if (paramsList.length === 0) return [];
+    const res = await this.batchPull([collection], { params: { [collection]: paramsList } });
+    return res.collections[collection] ?? [];
+  }
   /**
    * Push synced data to the server.
    * @param path - The push endpoint path (e.g. "/push/users/abc/settings")
@@ -535,8 +544,7 @@ var StarfishClient = class {
           documentKey,
           data,
           authorKey.authorPubHex,
-          capCtx.devEdPrivHex,
-          authorKey.signAlg
+          capCtx.devEdPrivHex
         );
         bodyObj[AUTHOR_PUBKEY_FIELD] = authorPubkey;
         bodyObj[AUTHOR_SIGNATURE_FIELD] = authorSignature;