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

package/dist/index.js

@@ -1,10 +1,24 @@
 // src/index.ts
 import { configurePlatform } from "@drakkar.software/starfish-protocol";
-import { stableStringify as stableStringify3, computeHash } from "@drakkar.software/starfish-protocol";
+import { stableStringify as stableStringify2, computeHash } from "@drakkar.software/starfish-protocol";
 import { buildRevocationList, revocationListCanonicalSigningInput } from "@drakkar.software/starfish-protocol";
 
 // src/client.ts
 import {
+  AUTHOR_PUBKEY_FIELD,
+  AUTHOR_SIGNATURE_FIELD,
+  DATA_FIELD,
+  TS_FIELD,
+  BASE_HASH_FIELD,
+  PUSH_PATH_PREFIX,
+  HEADER_AUTHORIZATION,
+  HEADER_SIG,
+  HEADER_TS,
+  HEADER_NONCE,
+  HEADER_PUB,
+  HEADER_CONTENT_TYPE,
+  HEADER_ACCEPT,
+  signAppendAuthor,
   signRequest,
   stableStringify
 } from "@drakkar.software/starfish-protocol";
@@ -27,6 +41,16 @@ var StarfishHttpError = class extends Error {
 
 // src/client.ts
 var APPEND_DEFAULT_FIELD = "items";
+function pullCacheKey(pathAndQuery) {
+  const q = pathAndQuery.indexOf("?");
+  return q === -1 ? pathAndQuery : pathAndQuery.slice(0, q);
+}
+function pullWasFromCache(result) {
+  return result.fromCache === true;
+}
+function stripPushPrefix(path) {
+  return path.startsWith(PUSH_PATH_PREFIX) ? path.slice(PUSH_PATH_PREFIX.length) : path;
+}
 function encodeCapAuth(cap) {
   const json = stableStringify(cap);
   if (typeof btoa === "function") {
@@ -38,8 +62,11 @@ function encodeCapAuth(cap) {
 }
 var StarfishClient = class {
   baseUrl;
+  namespace;
   capProvider;
   fetch;
+  cache;
+  cacheMaxAgeMs;
   /**
    * Installed client-side plugins. Currently stored as inert data; no
    * hooks fire yet. Extensions can inspect this list if needed.
@@ -47,10 +74,22 @@ var StarfishClient = class {
   plugins;
   constructor(options) {
     this.baseUrl = options.baseUrl.replace(/\/$/, "");
+    this.namespace = options.namespace || void 0;
     this.capProvider = options.capProvider;
     this.fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+    this.cache = options.cache;
+    this.cacheMaxAgeMs = options.cacheMaxAgeMs;
     this.plugins = options.plugins ? [...options.plugins] : [];
   }
+  /**
+   * Mark a `PullResult` as having been served from the offline read-through
+   * cache (transport was unreachable). Non-enumerable so it doesn't leak into
+   * JSON / equality / re-caching; read via {@link pullWasFromCache}.
+   */
+  tagFromCache(result) {
+    Object.defineProperty(result, "fromCache", { value: true, enumerable: false });
+    return result;
+  }
   /**
    * Resolve the host portion of the URL the client will send to. The host
    * is folded into the signed canonical input as the `h` field so the
@@ -70,6 +109,20 @@ var StarfishClient = class {
       return "";
     }
   }
+  /**
+   * Rewrite a request path for the configured namespace. A no-op when no
+   * namespace is set; otherwise `/{action}/…` becomes `/v1/{namespace}/{action}/…`
+   * (the `/v1` protocol-version segment is part of the namespaced route, matching
+   * the Python client and the server's namespace mount).
+   *
+   * Applied to the path used for BOTH the signature and the URL so the canonical
+   * path the client signs equals the path the server reconstructs from the URL.
+   * Covers SDK-helper-built paths too — that's the point: a namespace-unaware
+   * helper passing `/push/spaces/x/_keyring` reaches `/v1/{ns}/push/spaces/x/_keyring`.
+   */
+  applyNamespace(path) {
+    return this.namespace ? `/v1/${this.namespace}${path}` : path;
+  }
   /**
    * Build auth headers for a request. When a `capProvider` is set, signs the
    * request with the device's Ed25519 private key and returns the v3 header
@@ -81,28 +134,52 @@ var StarfishClient = class {
    * The host bound into the signature is derived from `baseUrl` once per call.
    */
   async buildAuthHeaders(method, pathAndQuery, body) {
-    if (this.capProvider) {
-      const { cap, devEdPrivHex, pubHex } = await this.capProvider.getCap();
-      const req = {
-        method,
-        pathAndQuery,
-        body,
-        host: this.signingHost()
-      };
-      const { sig, ts, nonce } = await signRequest(req, devEdPrivHex);
-      const headers = {
-        Authorization: `Cap ${encodeCapAuth(cap)}`,
-        "X-Starfish-Sig": sig,
-        "X-Starfish-Ts": String(ts),
-        "X-Starfish-Nonce": nonce
-      };
-      if (pubHex !== void 0) headers["X-Starfish-Pub"] = pubHex;
-      return headers;
-    }
-    return {};
+    if (!this.capProvider) return {};
+    const capCtx = await this.capProvider.getCap();
+    return this.capRequestHeaders(capCtx, method, pathAndQuery, body);
+  }
+  /**
+   * Build the request-signing headers from an ALREADY-fetched cap context. Split
+   * out of {@link buildAuthHeaders} so {@link append} can fetch the cap once and
+   * reuse it for BOTH the author signature (over the element data) and the
+   * request signature (over the body), without redeeming the cap twice — a
+   * second `getCap()` could rotate keys and break the `authorPubkey ===
+   * presenter` bind the server checks.
+   */
+  async capRequestHeaders(capCtx, method, pathAndQuery, body) {
+    const { cap, devEdPrivHex, pubHex } = capCtx;
+    const req = {
+      method,
+      pathAndQuery,
+      body,
+      host: this.signingHost()
+    };
+    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
+    };
+    if (pubHex !== void 0) headers[HEADER_PUB] = pubHex;
+    return headers;
+  }
+  /**
+   * Resolve the author public key to attach to a signed append: the redeemer's
+   * `pubHex` for an audience cap, else the cert subject `cap.sub` for a
+   * device/member cap. This is the SAME key that signs the request, so a server
+   * enforcing author proof can bind the stored element to its writer. Returns
+   * undefined only for a (malformed) cap with neither — the append then goes
+   * unsigned and a server requiring signatures rejects it.
+   */
+  appendAuthorKey(capCtx) {
+    const { cap, pubHex } = capCtx;
+    const authorPubHex = pubHex ?? cap.sub;
+    if (authorPubHex === void 0) return null;
+    return { authorPubHex };
   }
   async pull(path, checkpointOrOptions) {
-    let pathAndQuery = path;
+    let pathAndQuery = this.applyNamespace(path);
     let appendField;
     if (typeof checkpointOrOptions === "number") {
       if (checkpointOrOptions) pathAndQuery += `?checkpoint=${checkpointOrOptions}`;
@@ -119,23 +196,43 @@ var StarfishClient = class {
         }
       } else {
         appendField = opts.appendField ?? APPEND_DEFAULT_FIELD;
+        if (opts.full && (opts.since != null || opts.limit != null || opts.last != null)) {
+          throw new Error("full cannot be combined with since, limit, or last");
+        }
         if (opts.since != null) {
           if (opts.since < 0) throw new Error("since must be non-negative");
           params.set("checkpoint", String(opts.since));
         }
+        if (opts.limit != null) {
+          if (opts.limit < 0) throw new Error("limit must be non-negative");
+          params.set("limit", String(opts.limit));
+        }
         if (opts.last != null) {
           if (opts.last < 0) throw new Error("last must be non-negative");
           params.set("last", String(opts.last));
         }
+        if (opts.full) {
+          params.set("full", "true");
+        }
       }
       if (params.size > 0) pathAndQuery += `?${params.toString()}`;
     }
     const url = `${this.baseUrl}${pathAndQuery}`;
     const authHeaders = await this.buildAuthHeaders("GET", pathAndQuery, void 0);
-    const res = await this.fetch(url, {
-      method: "GET",
-      headers: { Accept: "application/json", ...authHeaders }
-    });
+    const cacheKey = this.cache && appendField === void 0 ? pullCacheKey(pathAndQuery) : void 0;
+    let res;
+    try {
+      res = await this.fetch(url, {
+        method: "GET",
+        headers: { [HEADER_ACCEPT]: "application/json", ...authHeaders }
+      });
+    } catch (err) {
+      if (cacheKey) {
+        const cached = await this.readCache(cacheKey);
+        if (cached) return cached;
+      }
+      throw err;
+    }
     if (!res.ok) {
       throw new StarfishHttpError(res.status, await res.text());
     }
@@ -144,29 +241,118 @@ var StarfishClient = class {
       const list = result.data?.[appendField];
       return Array.isArray(list) ? list : [];
     }
+    if (cacheKey) {
+      const snapshot = {
+        data: result.data,
+        hash: result.hash,
+        timestamp: result.timestamp,
+        cachedAt: Date.now()
+      };
+      void this.cache.set(cacheKey, JSON.stringify(snapshot)).catch(() => {
+      });
+    }
     return result;
   }
+  /**
+   * Read the cached snapshot for a document `path` WITHOUT hitting the network —
+   * the basis for cache-first paint (seed the UI from the last-synced snapshot,
+   * then revalidate with a live {@link pull}). Returns the tagged `PullResult`,
+   * or null when no cache is configured / there's no entry. Namespacing matches
+   * {@link pull}, so the key lines up with whatever `pull` wrote.
+   */
+  async peekCache(path) {
+    if (!this.cache) return null;
+    return this.readCache(pullCacheKey(this.applyNamespace(path)));
+  }
+  /** Read + parse a cached pull snapshot, tagged {@link tagFromCache}. Returns
+   *  null on a miss or an unparseable blob (never throws — a corrupt cache entry
+   *  must not break a pull, just miss). */
+  async readCache(cacheKey) {
+    try {
+      const raw = await this.cache.get(cacheKey);
+      if (!raw) return null;
+      const parsed = JSON.parse(raw);
+      if (!parsed || typeof parsed.hash !== "string") return null;
+      if (this.cacheMaxAgeMs != null && Date.now() - (parsed.cachedAt ?? 0) > this.cacheMaxAgeMs) {
+        return null;
+      }
+      return this.tagFromCache({ data: parsed.data ?? {}, hash: parsed.hash, timestamp: parsed.timestamp ?? 0 });
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * 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.
+   */
+  async batchPull(collections, opts = {}) {
+    const search = new URLSearchParams();
+    search.set("collections", collections.join(","));
+    if (opts.params && Object.keys(opts.params).length > 0) {
+      search.set("params", JSON.stringify(opts.params));
+    }
+    const pathAndQuery = `${this.applyNamespace("/batch/pull")}?${search.toString()}`;
+    const url = `${this.baseUrl}${pathAndQuery}`;
+    const authHeaders = await this.buildAuthHeaders("GET", pathAndQuery, void 0);
+    const res = await this.fetch(url, {
+      method: "GET",
+      headers: { [HEADER_ACCEPT]: "application/json", ...authHeaders }
+    });
+    if (!res.ok) {
+      throw new StarfishHttpError(res.status, await res.text());
+    }
+    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")
    * @param data - The full document data to push
    * @param baseHash - Hash of the document this push is based on (null for first push)
    *
-   * v3 author fields (`authorPubkey` + `authorSignature`) live inside `data`
-   * and are produced by `SyncManager` when a `signer` is configured.
+   * v3 author proof (`authorPubkey` + `authorSignature`) is passed via `author`
+   * (produced by `SyncManager` when a `signer` is configured) and sent as
+   * top-level body siblings of `data`, where the server verifies it.
    * @throws {ConflictError} if the server detects a hash mismatch (409)
    */
-  async push(path, data, baseHash) {
+  async push(path, data, baseHash, author) {
     const body = JSON.stringify({
-      data,
-      baseHash
+      [DATA_FIELD]: data,
+      [BASE_HASH_FIELD]: baseHash,
+      ...author && {
+        [AUTHOR_PUBKEY_FIELD]: author.authorPubkey,
+        [AUTHOR_SIGNATURE_FIELD]: author.authorSignature
+      }
     });
-    const authHeaders = await this.buildAuthHeaders("POST", path, body);
-    const res = await this.fetch(`${this.baseUrl}${path}`, {
+    const sendPath = this.applyNamespace(path);
+    const authHeaders = await this.buildAuthHeaders("POST", sendPath, body);
+    const res = await this.fetch(`${this.baseUrl}${sendPath}`, {
       method: "POST",
       headers: {
-        "Content-Type": "application/json",
-        Accept: "application/json",
+        [HEADER_CONTENT_TYPE]: "application/json",
+        [HEADER_ACCEPT]: "application/json",
         ...authHeaders
       },
       body
@@ -193,19 +379,37 @@ var StarfishClient = class {
    * @param opts.ts - optional client-supplied element timestamp (ms). Must be a
    *   non-negative integer strictly greater than the latest stored element's ts
    *   (else the server responds 409). Omit to let the server assign one.
-   * @throws {StarfishHttpError} on a non-2xx response (e.g. 409 for a
-   *   non-monotonic timestamp).
+   * @throws {StarfishHttpError} on a non-2xx response — e.g. 409
+   *   `{ error: "non_monotonic_timestamp" }` for a non-monotonic timestamp, or
+   *   `{ error: "append_limit_exceeded", limit }` if the collection's `maxItems`
+   *   cap is reached (partition by a path parameter for higher volume).
    */
   async append(path, data, opts = {}) {
-    const bodyObj = { data };
-    if (opts.ts !== void 0) bodyObj["ts"] = opts.ts;
+    const sendPath = this.applyNamespace(path);
+    const bodyObj = { [DATA_FIELD]: data };
+    if (opts.ts !== void 0) bodyObj[TS_FIELD] = opts.ts;
+    const capCtx = this.capProvider ? await this.capProvider.getCap() : null;
+    if (capCtx) {
+      const authorKey = this.appendAuthorKey(capCtx);
+      if (authorKey) {
+        const documentKey = stripPushPrefix(path);
+        const { authorPubkey, authorSignature } = signAppendAuthor(
+          documentKey,
+          data,
+          authorKey.authorPubHex,
+          capCtx.devEdPrivHex
+        );
+        bodyObj[AUTHOR_PUBKEY_FIELD] = authorPubkey;
+        bodyObj[AUTHOR_SIGNATURE_FIELD] = authorSignature;
+      }
+    }
     const body = JSON.stringify(bodyObj);
-    const authHeaders = await this.buildAuthHeaders("POST", path, body);
-    const res = await this.fetch(`${this.baseUrl}${path}`, {
+    const authHeaders = capCtx ? await this.capRequestHeaders(capCtx, "POST", sendPath, body) : {};
+    const res = await this.fetch(`${this.baseUrl}${sendPath}`, {
       method: "POST",
       headers: {
-        "Content-Type": "application/json",
-        Accept: "application/json",
+        [HEADER_CONTENT_TYPE]: "application/json",
+        [HEADER_ACCEPT]: "application/json",
         ...authHeaders
       },
       body
@@ -220,16 +424,17 @@ var StarfishClient = class {
    * Returns raw bytes with the content hash from the ETag header.
    */
   async pullBlob(path) {
-    const authHeaders = await this.buildAuthHeaders("GET", path, void 0);
-    const res = await this.fetch(`${this.baseUrl}${path}`, {
+    const sendPath = this.applyNamespace(path);
+    const authHeaders = await this.buildAuthHeaders("GET", sendPath, void 0);
+    const res = await this.fetch(`${this.baseUrl}${sendPath}`, {
       method: "GET",
-      headers: { Accept: "*/*", ...authHeaders }
+      headers: { [HEADER_ACCEPT]: "*/*", ...authHeaders }
     });
     if (!res.ok) {
       throw new StarfishHttpError(res.status, await res.text());
     }
     const etag = res.headers.get("ETag")?.replace(/"/g, "") ?? null;
-    const contentType = res.headers.get("Content-Type") ?? "application/octet-stream";
+    const contentType = res.headers.get(HEADER_CONTENT_TYPE) ?? "application/octet-stream";
     const data = await res.arrayBuffer();
     return { data, hash: etag, contentType };
   }
@@ -238,12 +443,13 @@ var StarfishClient = class {
    * Binary collections use last-write-wins (no conflict detection).
    */
   async pushBlob(path, data, contentType) {
-    const authHeaders = await this.buildAuthHeaders("POST", path, void 0);
-    const res = await this.fetch(`${this.baseUrl}${path}`, {
+    const sendPath = this.applyNamespace(path);
+    const authHeaders = await this.buildAuthHeaders("POST", sendPath, void 0);
+    const res = await this.fetch(`${this.baseUrl}${sendPath}`, {
       method: "POST",
       headers: {
-        "Content-Type": contentType,
-        Accept: "application/json",
+        [HEADER_CONTENT_TYPE]: contentType,
+        [HEADER_ACCEPT]: "application/json",
         ...authHeaders
       },
       body: data
@@ -256,7 +462,13 @@ var StarfishClient = class {
 };
 
 // src/sync.ts
-import { deepMerge, getBase64, stableStringify as stableStringify2 } from "@drakkar.software/starfish-protocol";
+import {
+  AUTHOR_PUBKEY_FIELD as AUTHOR_PUBKEY_FIELD2,
+  AUTHOR_SIGNATURE_FIELD as AUTHOR_SIGNATURE_FIELD2,
+  deepMerge,
+  docAuthorCanonicalInput,
+  getBase64
+} from "@drakkar.software/starfish-protocol";
 
 // src/validate.ts
 var ValidationError = class extends Error {
@@ -296,6 +508,7 @@ var SyncManager = class {
   lastCheckpoint = 0;
   localData = {};
   aborted = false;
+  lastFromCache = false;
   constructor(options) {
     this.client = options.client;
     this.pullPath = options.pullPath;
@@ -317,6 +530,18 @@ var SyncManager = class {
   getData() {
     return { ...this.localData };
   }
+  /**
+   * Merge a remote snapshot with local (optimistic) data using this manager's
+   * conflict resolver — the same resolver the push-conflict path uses. A plain
+   * {@link pull} overwrites the store's data with the server snapshot, which
+   * would drop un-pushed local writes (they live only in the store, never in
+   * `localData` until a push succeeds). The zustand binding calls this on pull
+   * while the store is dirty so those writes survive. `local` wins by the same
+   * rules as a push conflict.
+   */
+  resolve(local, remote) {
+    return this.onConflict(local, remote);
+  }
   getHash() {
     return this.lastHash;
   }
@@ -324,6 +549,40 @@ var SyncManager = class {
   setHash(hash) {
     this.lastHash = hash;
   }
+  /**
+   * Whether the most recent {@link pull} (or {@link seedFromCache}) was served
+   * from the client's offline read-through cache rather than a live server
+   * response. The binding surfaces this as a `stale` flag so the UI can show an
+   * offline indicator without treating a cache hit as "reachable". Reset to
+   * false by the next successful network pull.
+   */
+  getLastPullFromCache() {
+    return this.lastFromCache;
+  }
+  /**
+   * Cache-first paint: seed `localData` from the client's read-through cache
+   * WITHOUT touching the network, decrypting in memory for E2E collections.
+   * Returns whether anything was seeded (false on a miss, an expired entry, or
+   * a decrypt failure — e.g. keyring skew). Call once on store creation before
+   * the initial live {@link pull}, which then supersedes the seeded snapshot.
+   * Requires the client to have been built with a `cache`.
+   */
+  async seedFromCache() {
+    if (this.aborted) return false;
+    const cached = await this.client.peekCache(this.pullPath);
+    if (!cached) return false;
+    let data;
+    try {
+      data = this.encryptor ? await this.encryptor.decrypt(cached.data) : cached.data;
+    } catch {
+      return false;
+    }
+    if (this.aborted) return false;
+    this.localData = data;
+    this.lastHash = cached.hash;
+    this.lastFromCache = true;
+    return true;
+  }
   getCheckpoint() {
     return this.lastCheckpoint;
   }
@@ -334,6 +593,7 @@ var SyncManager = class {
     try {
       const result = await this.client.pull(this.pullPath, this.lastCheckpoint);
       if (this.aborted) throw new AbortError();
+      this.lastFromCache = pullWasFromCache(result);
       if (this.encryptor) {
         const decrypted = await this.encryptor.decrypt(result.data);
         if (this.aborted) throw new AbortError();
@@ -368,23 +628,24 @@ var SyncManager = class {
       try {
         const sealed = this.encryptor ? await this.encryptor.encrypt(pendingData) : pendingData;
         if (this.aborted) throw new AbortError();
-        let payload = sealed;
+        let author;
         if (this.signer) {
           const { devEdPubHex, sign } = await this.signer.getSigner();
           if (this.aborted) throw new AbortError();
-          const canonical = stableStringify2(sealed);
+          const documentKey = stripPushPrefix(this.pushPath);
+          const canonical = docAuthorCanonicalInput(documentKey, sealed);
           const sigBytes = await sign(new TextEncoder().encode(canonical));
           if (this.aborted) throw new AbortError();
-          payload = {
-            ...sealed,
-            authorPubkey: devEdPubHex,
-            authorSignature: getBase64().encode(sigBytes)
+          author = {
+            [AUTHOR_PUBKEY_FIELD2]: devEdPubHex,
+            [AUTHOR_SIGNATURE_FIELD2]: getBase64().encode(sigBytes)
           };
         }
         const result = await this.client.push(
           this.pushPath,
-          payload,
-          this.lastHash
+          sealed,
+          this.lastHash,
+          author
         );
         if (this.aborted) throw new AbortError();
         this.lastHash = result.hash;
@@ -426,6 +687,208 @@ var SyncManager = class {
   }
 };
 
+// src/append-log.ts
+import {
+  verifyAppendAuthor
+} from "@drakkar.software/starfish-protocol";
+var PULL_PATH_PREFIX = "/pull/";
+function stripPullPrefix(path) {
+  return path.startsWith(PULL_PATH_PREFIX) ? path.slice(PULL_PATH_PREFIX.length) : path;
+}
+var AppendAuthorError = class extends Error {
+  constructor(ts) {
+    super(`append element author verification failed (ts=${ts})`);
+    this.ts = ts;
+    this.name = "AppendAuthorError";
+  }
+};
+function checkpointOf(items) {
+  let max = 0;
+  for (const it of items) if (it.ts > max) max = it.ts;
+  return max;
+}
+function withAuthor(ts, data, src) {
+  const out = { ts, data };
+  if (src.authorPubkey !== void 0) out.authorPubkey = src.authorPubkey;
+  if (src.authorSignature !== void 0) out.authorSignature = src.authorSignature;
+  return out;
+}
+var AppendLogCursor = class {
+  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() {
+    const run = this.pullChain.then(
+      () => this.doPull(),
+      () => this.doPull()
+    );
+    this.pullChain = run.then(
+      () => void 0,
+      () => void 0
+    );
+    return run;
+  }
+  async doPull() {
+    this.logger?.pullStart(this.loggerName);
+    const start = performance.now();
+    try {
+      const since = this.lastCheckpoint;
+      const opts = since > 0 ? { appendField: this.appendField, since } : { appendField: this.appendField, full: true };
+      const raw = await this.client.pull(this.pullPath, opts);
+      const batch = [];
+      const stored = [];
+      let maxTs = since;
+      let skipped = 0;
+      for (const el of raw) {
+        if (since > 0 && el.ts <= since) continue;
+        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) {
+          if (this.onElementError !== "skip") throw err;
+          skipped++;
+        }
+        if (this.persistEncrypted) {
+          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 } : void 0
+      );
+      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);
+    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;
+  }
+};
+
 // src/index.ts
 import { ENCRYPTED_KEY } from "@drakkar.software/starfish-protocol";
 
@@ -839,6 +1302,32 @@ function createDedupFetch(baseFetch = globalThis.fetch.bind(globalThis)) {
   });
 }
 
+// src/mutate.ts
+async function mutateDoc(client, path, mutator, options = {}) {
+  const maxAttempts = Math.max(1, options.maxAttempts ?? 3);
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    let data = null;
+    let hash = null;
+    try {
+      const res = await client.pull(path);
+      data = res.data ?? null;
+      hash = res.hash ?? null;
+    } catch (err) {
+      if (!(err instanceof StarfishHttpError) || err.status !== 404) throw err;
+    }
+    const next = mutator({ data, hash });
+    if (next === null) return null;
+    try {
+      await client.push(path, next, hash);
+      return next;
+    } catch (err) {
+      if (err instanceof ConflictError && attempt < maxAttempts - 1) continue;
+      throw err;
+    }
+  }
+  throw new ConflictError();
+}
+
 // src/config.ts
 async function fetchServerConfig(baseUrl, options) {
   const url = `${baseUrl.replace(/\/$/, "")}/config`;
@@ -1211,6 +1700,29 @@ function createMobileLifecycle(store, deps, options = {}) {
     netUnsub?.();
   };
 }
+function createAppendLogMobileLifecycle(store, deps, options = {}) {
+  const { pullOnForeground = true } = options;
+  const appSub = deps.appState.addEventListener("change", (appState) => {
+    if (appState === "active" && pullOnForeground) {
+      const { online, loading } = store.getState();
+      if (online && !loading) {
+        store.getState().pull().catch((err) => {
+          console.error("[Starfish] foreground log pull failed:", err);
+        });
+      }
+    }
+  });
+  let netUnsub = null;
+  if (deps.netInfo) {
+    netUnsub = deps.netInfo.addEventListener(({ isConnected }) => {
+      store.getState().setOnline(!!isConnected);
+    });
+  }
+  return () => {
+    appSub.remove();
+    netUnsub?.();
+  };
+}
 
 // src/multi-store.ts
 function createMultiStoreSync(options) {
@@ -1263,6 +1775,8 @@ function createMultiStoreSync(options) {
 }
 export {
   AbortError,
+  AppendAuthorError,
+  AppendLogCursor,
   ConflictError,
   ENCRYPTED_KEY,
   SnapshotHistory,
@@ -1271,10 +1785,12 @@ export {
   SyncManager,
   ValidationError,
   buildRevocationList,
+  checkpointOf,
   classifyError,
   computeHash,
   configurePlatform,
   consoleSyncLogger,
+  createAppendLogMobileLifecycle,
   createDebouncedPush,
   createDebouncedSync,
   createDedupFetch,
@@ -1293,12 +1809,14 @@ export {
   importData,
   isBackgroundSyncSupported,
   isServiceWorkerSupported,
+  mutateDoc,
   noopSyncLogger,
   pruneTombstones,
+  pullWasFromCache,
   registerBackgroundSync,
   registerServiceWorker,
   revocationListCanonicalSigningInput,
-  stableStringify3 as stableStringify,
+  stableStringify2 as stableStringify,
   startAdaptivePolling,
   startPolling,
   timestampWinner,