@drakkar.software/starfish-client 3.0.0-alpha.14 → 3.0.0-alpha.18

package/dist/mobile-lifecycle.js

@@ -31,13 +31,13 @@ export function createMobileLifecycle(store, deps, options = {}) {
     const appSub = deps.appState.addEventListener("change", (appState) => {
         if (appState === "background" && flushOnBackground) {
             if (store.getState().dirty) {
-                store.getState().flush().catch((err) => { console.error("[Starfish] background flush failed:", err); });
+                store.getState().flush().catch(() => { });
             }
         }
         else if (appState === "active" && pullOnForeground) {
             const { online, syncing } = store.getState();
             if (online && !syncing) {
-                store.getState().pull().catch((err) => { console.error("[Starfish] foreground pull failed:", err); });
+                store.getState().pull().catch(() => { });
             }
         }
         // "inactive" (iOS transition) and other states are intentionally ignored
@@ -53,42 +53,3 @@ export function createMobileLifecycle(store, deps, options = {}) {
         netUnsub?.();
     };
 }
-/**
- * Wires React Native app lifecycle events to an append-log store
- * (`createStarfishLog`). A log is read-only, so this only pulls on foreground
- * (there is nothing to flush on background). NetInfo connectivity changes are
- * forwarded to `store.getState().setOnline()`.
- *
- * ```ts
- * import { AppState } from "react-native"
- * import NetInfo from "@react-native-community/netinfo"
- * import { createStarfishLog, createAppendLogMobileLifecycle } from "@drakkar.software/starfish-client"
- *
- * const store = createStarfishLog({ cursor })
- * const cleanup = createAppendLogMobileLifecycle(store, { appState: AppState, netInfo: NetInfo })
- * useEffect(() => cleanup, [])
- * ```
- *
- * @returns A cleanup function that removes all event listeners.
- */
-export 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?.();
-    };
-}

package/dist/polling.js

@@ -14,7 +14,7 @@ export function startPolling(pullFn, getState, intervalMs = 30_000) {
     const timer = setInterval(() => {
         const { online, syncing } = getState();
         if (online && !syncing)
-            pullFn().catch((err) => { console.error("[Starfish] poll failed:", err); });
+            pullFn().catch(() => { });
     }, intervalMs);
     return () => clearInterval(timer);
 }
@@ -42,7 +42,7 @@ export function startAdaptivePolling(pullFn, getState, options) {
             return;
         const { online, syncing } = getState();
         if (online && !syncing)
-            pullFn().catch((err) => { console.error("[Starfish] adaptive poll failed:", err); });
+            pullFn().catch(() => { });
     }, intervalMs);
     return {
         pause: () => { paused = true; },

package/dist/sync.d.ts

@@ -70,6 +70,7 @@ export declare class SyncManager {
     private lastCheckpoint;
     private localData;
     private aborted;
+    private lastFromCache;
     constructor(options: SyncManagerOptions);
     abort(): void;
     get isAborted(): boolean;
@@ -87,6 +88,23 @@ export declare class SyncManager {
     getHash(): string | null;
     /** Set the last-known server hash. Used by persistence layers to restore state across restarts. */
     setHash(hash: string | null): void;
+    /**
+     * 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(): boolean;
+    /**
+     * 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`.
+     */
+    seedFromCache(): Promise<boolean>;
     getCheckpoint(): number;
     pull(): Promise<PullResult>;
     push(data: Record<string, unknown>): Promise<{

package/dist/sync.js

@@ -1,13 +1,7 @@
-import { AUTHOR_PUBKEY_FIELD, AUTHOR_SIGNATURE_FIELD, deepMerge, docAuthorCanonicalInput, getBase64, } from "@drakkar.software/starfish-protocol";
+import { deepMerge, stableStringify } from "@drakkar.software/starfish-protocol";
 import { ConflictError } from "./types.js";
-import { stripPushPrefix } from "./client.js";
+import { createEncryptor } from "./crypto.js";
 import { ValidationError } from "./validate.js";
-export class AbortError extends Error {
-    constructor() {
-        super("SyncManager was aborted");
-        this.name = "AbortError";
-    }
-}
 export class SyncManager {
     client;
     pullPath;
@@ -15,31 +9,28 @@ export class SyncManager {
     onConflict;
     maxRetries;
     encryptor;
-    signer;
+    signData;
     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.signer = options.signer;
+        this.signData = options.signData;
         this.logger = options.logger;
         this.loggerName = options.loggerName ?? options.pullPath.split("/").filter(Boolean).pop() ?? options.pullPath;
         this.validate = options.validate;
-        this.encryptor = options.encryptor ?? null;
-    }
-    abort() {
-        this.aborted = true;
-    }
-    get isAborted() {
-        return this.aborted;
+        this.encryptor =
+            options.encryptor ??
+                (options.encryptionSecret && options.encryptionSalt
+                    ? createEncryptor(options.encryptionSecret, options.encryptionSalt, options.encryptionInfo)
+                    : null);
     }
     getData() {
         return { ...this.localData };
@@ -47,31 +38,16 @@ 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;
             }
@@ -93,8 +69,6 @@ export class SyncManager {
         }
     }
     async push(data) {
-        if (this.aborted)
-            throw new AbortError();
         if (this.validate) {
             const result = this.validate(data);
             if (result !== true)
@@ -106,33 +80,13 @@ export class SyncManager {
         let pendingData = data;
         while (attempt <= this.maxRetries) {
             try {
-                const sealed = this.encryptor
+                const payload = this.encryptor
                     ? await this.encryptor.encrypt(pendingData)
                     : pendingData;
-                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();
+                const sig = this.signData
+                    ? await this.signData(stableStringify(payload))
+                    : undefined;
+                const result = await this.client.push(this.pushPath, payload, this.lastHash, sig);
                 this.lastHash = result.hash;
                 this.lastCheckpoint = result.timestamp;
                 this.localData = pendingData;
@@ -140,8 +94,6 @@ 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;
@@ -149,20 +101,14 @@ 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/dist/types.d.ts

@@ -36,6 +36,26 @@ export interface StarfishCapProvider {
         pubHex?: string;
     }>;
 }
+/**
+ * A minimal async key-value store the client uses as a read-through cache for
+ * {@link StarfishClient.pull} (offline-first reads). Host-provided so the SDK
+ * stays storage-agnostic — back it by `localStorage`, `AsyncStorage`, a file,
+ * etc. Shaped like a subset of zustand's `StateStorage` so an existing adapter
+ * fits.
+ *
+ * IMPORTANT — what gets stored: the client caches the RAW server response only
+ * (`data`/`hash`/`timestamp`). For E2E (`delegated`) collections that payload is
+ * the SEALED ciphertext the server holds — never the decrypted form — so this
+ * cache is ciphertext-at-rest by construction. Decryption always happens in
+ * memory on read (see {@link SyncManager}). Public/plaintext collections cache
+ * their plaintext, exactly as the server stores it.
+ */
+export interface PullCache {
+    /** Return the previously-stored string for `key`, or null if absent. Must not throw. */
+    get(key: string): Promise<string | null>;
+    /** Store `value` under `key`. Must not throw (failures are swallowed by the client). */
+    set(key: string, value: string): Promise<void>;
+}
 /** Options for creating a StarfishClient. */
 export interface StarfishClientOptions {
     /** Base URL of the Starfish server (e.g. "https://api.example.com/v1"). */
@@ -66,6 +86,29 @@ export interface StarfishClientOptions {
     capProvider?: StarfishCapProvider;
     /** Optional fetch implementation (defaults to global fetch). */
     fetch?: typeof fetch;
+    /**
+     * Optional read-through cache for {@link StarfishClient.pull} — the basis for
+     * offline-first reads. When set, every successful non-append pull is written
+     * through to the cache (keyed by document path), and a pull that fails because
+     * the TRANSPORT is unreachable (offline / DNS / timeout — `fetch` rejects)
+     * falls back to the cached response, tagged so callers can tell it's stale.
+     *
+     * A real HTTP error (404/403/5xx) is a genuine server answer and always
+     * propagates — the cache is NOT consulted — so "no document yet" and
+     * "access denied" keep their meaning. Caches ciphertext for E2E collections
+     * (the server only ever holds sealed payloads); never decrypted data.
+     */
+    cache?: PullCache;
+    /**
+     * Optional max age (ms) for {@link cache} entries. An entry older than this is
+     * treated as a cache MISS on every read — both cache-first paint and the
+     * offline fallback — so a stale-beyond-policy snapshot is never served (the
+     * pull then goes to the network, or rethrows the transport error offline).
+     * Each cached snapshot records its write time; expiry is `now - cachedAt >
+     * cacheMaxAgeMs`. Omit (default) for entries that never expire — recommended
+     * for an offline-first app where any last-synced data beats none.
+     */
+    cacheMaxAgeMs?: number;
     /**
      * Optional list of client-side plugins. The list is stored on the client
      * instance but does not fire any hooks yet — the contract is plumbed so

package/package.json

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

package/dist/_crypto_helpers.d.ts

@@ -1,4 +0,0 @@
-export declare function hkdfBytes(ikm: Uint8Array, salt: Uint8Array, info: Uint8Array, lengthBytes?: number): Promise<Uint8Array>;
-export declare function bytesToHex(bytes: Uint8Array): string;
-export declare function hexToBytes(hex: string): Uint8Array;
-export declare function concat(...parts: Uint8Array[]): Uint8Array;

package/dist/append-log.js

@@ -1,267 +0,0 @@
-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/cap-mint.d.ts

@@ -1,20 +0,0 @@
-/**
- * Phase-2 transitional shim. `mintDeviceCap` + `scopes.rootAll` now live in
- * `@drakkar.software/starfish-identities`; `mintMemberCap` +
- * `scopes.readOnly`/`scopes.writer`/`scopes.admin` now live in
- * `@drakkar.software/starfish-sharing`. The `scopes` re-export here merges
- * both so existing imports of `import { scopes } from
- * "../src/cap-mint.js"` keep working. Removed in Phase 3.
- */
-import { type ScopePreset as IdentityScopePreset, type MintOpts as IdentityMintOpts } from "@drakkar.software/starfish-identities";
-export { mintDeviceCap } from "@drakkar.software/starfish-identities";
-export { mintMemberCap } from "@drakkar.software/starfish-sharing";
-/** @deprecated Phase-2 transitional facade. Use the per-package `scopes` directly. */
-export declare const scopes: {
-    readOnly: (c: string) => import("@drakkar.software/starfish-sharing").ScopePreset;
-    writer: (c: string) => import("@drakkar.software/starfish-sharing").ScopePreset;
-    admin: (c: string) => import("@drakkar.software/starfish-sharing").ScopePreset;
-    rootAll: () => IdentityScopePreset;
-};
-export type ScopePreset = IdentityScopePreset;
-export type MintOpts = IdentityMintOpts;

package/dist/cap-mint.js

@@ -1,12 +0,0 @@
-// src/cap-mint.ts
-import { scopes as identityScopes } from "@drakkar.software/starfish-identities";
-import { scopes as sharingScopes } from "@drakkar.software/starfish-sharing";
-import { mintDeviceCap } from "@drakkar.software/starfish-identities";
-import { mintMemberCap } from "@drakkar.software/starfish-sharing";
-var scopes = { ...identityScopes, ...sharingScopes };
-export {
-  mintDeviceCap,
-  mintMemberCap,
-  scopes
-};
-//# sourceMappingURL=cap-mint.js.map

package/dist/cap-mint.js.map

@@ -1,7 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../src/cap-mint.ts"],
-  "sourcesContent": ["/**\n * Phase-2 transitional shim. `mintDeviceCap` + `scopes.rootAll` now live in\n * `@drakkar.software/starfish-identities`; `mintMemberCap` +\n * `scopes.readOnly`/`scopes.writer`/`scopes.admin` now live in\n * `@drakkar.software/starfish-sharing`. The `scopes` re-export here merges\n * both so existing imports of `import { scopes } from\n * \"../src/cap-mint.js\"` keep working. Removed in Phase 3.\n */\nimport { scopes as identityScopes, type ScopePreset as IdentityScopePreset, type MintOpts as IdentityMintOpts } from \"@drakkar.software/starfish-identities\"\nimport { scopes as sharingScopes } from \"@drakkar.software/starfish-sharing\"\n\nexport { mintDeviceCap } from \"@drakkar.software/starfish-identities\"\nexport { mintMemberCap } from \"@drakkar.software/starfish-sharing\"\n\n/** @deprecated Phase-2 transitional facade. Use the per-package `scopes` directly. */\nexport const scopes = { ...identityScopes, ...sharingScopes }\n\nexport type ScopePreset = IdentityScopePreset\nexport type MintOpts = IdentityMintOpts\n"],
-  "mappings": ";AAQA,SAAS,UAAU,sBAAkG;AACrH,SAAS,UAAU,qBAAqB;AAExC,SAAS,qBAAqB;AAC9B,SAAS,qBAAqB;AAGvB,IAAM,SAAS,EAAE,GAAG,gBAAgB,GAAG,cAAc;",
-  "names": []
-}