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

package/dist/client.d.ts

@@ -1,6 +1,13 @@
 import type { PullResult, PushSuccess } from "@drakkar.software/starfish-protocol";
 import { type AppendAuthor } from "@drakkar.software/starfish-protocol";
 import type { StarfishClientOptions } from "./types.js";
+/**
+ * Whether a {@link PullResult} was served from the offline read-through cache
+ * (the transport was unreachable) rather than a live server response. Used by
+ * {@link SyncManager} to surface a `stale` flag to the UI without treating a
+ * cache hit as proof the server is reachable.
+ */
+export declare function pullWasFromCache(result: PullResult): boolean;
 /** The storage `documentKey` for a push `path`: the path with the `/push/`
  *  action prefix stripped (the namespace lives only in the URL). The author
  *  signature binds to this key. */
@@ -76,12 +83,20 @@ export declare class StarfishClient {
     private readonly namespace?;
     private readonly capProvider?;
     private readonly fetch;
+    private readonly cache?;
+    private readonly cacheMaxAgeMs?;
     /**
      * Installed client-side plugins. Currently stored as inert data; no
      * hooks fire yet. Extensions can inspect this list if needed.
      */
     readonly plugins: ReadonlyArray<import("./types.js").ClientPlugin>;
     constructor(options: StarfishClientOptions);
+    /**
+     * 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}.
+     */
+    private tagFromCache;
     /**
      * 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
@@ -142,6 +157,18 @@ export declare class StarfishClient {
     pull(path: string, options: PullOptions): Promise<PullResult>;
     /** Pull an append-only collection. Extracts and returns `data[appendField]` as `T[]`. */
     pull<T = unknown>(path: string, options: AppendPullOptions): Promise<T[]>;
+    /**
+     * 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.
+     */
+    peekCache(path: string): Promise<PullResult | null>;
+    /** 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). */
+    private readCache;
     /**
      * Pull several documents in one round-trip via `/batch/pull`. `collections` is
      * the list of distinct collection names; `opts.params` supplies, per collection,

package/dist/client.js

@@ -1,277 +1,60 @@
-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";
 import { ConflictError, StarfishHttpError } from "./types.js";
-const APPEND_DEFAULT_FIELD = "items";
-/** The storage `documentKey` for a push `path`: the path with the `/push/`
- *  action prefix stripped (the namespace lives only in the URL). The author
- *  signature binds to this key. */
-export function stripPushPrefix(path) {
-    return path.startsWith(PUSH_PATH_PREFIX) ? path.slice(PUSH_PATH_PREFIX.length) : path;
-}
-/**
- * Base64-encode the canonical stable-stringification of a cap-cert.
- *
- * Used as the value of the `Authorization: Cap <…>` header in v3.0. We rely
- * on the host's `btoa` for browsers and fall back to `Buffer` in Node so the
- * client stays free of native dependencies.
- */
-function encodeCapAuth(cap) {
-    const json = stableStringify(cap);
-    if (typeof btoa === "function") {
-        return btoa(json);
-    }
-    const bufCtor = globalThis.Buffer;
-    if (bufCtor)
-        return bufCtor.from(json, "utf-8").toString("base64");
-    throw new Error("No base64 encoder available");
-}
 /**
  * Low-level HTTP client for the Starfish sync protocol.
  * Handles auth headers and response parsing.
  */
 export class StarfishClient {
     baseUrl;
-    namespace;
-    capProvider;
+    auth;
     fetch;
-    /**
-     * Installed client-side plugins. Currently stored as inert data; no
-     * hooks fire yet. Extensions can inspect this list if needed.
-     */
-    plugins;
     constructor(options) {
         this.baseUrl = options.baseUrl.replace(/\/$/, "");
-        // Empty string ⇒ no namespace (treat like unset), so a falsy env value
-        // doesn't produce a malformed `/v1//…` path.
-        this.namespace = options.namespace || undefined;
-        this.capProvider = options.capProvider;
+        this.auth = options.auth;
         this.fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
-        this.plugins = options.plugins ? [...options.plugins] : [];
-    }
-    /**
-     * 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
-     * server can refuse a signature that was minted against a different
-     * Starfish host (replay-across-servers defence).
-     *
-     * When `baseUrl` is relative — e.g. the consumer passed a custom `fetch`
-     * that resolves relative URLs in its own context — there is no parseable
-     * host; we return `""` so signing still proceeds. The server-side
-     * verifier will also reconstruct host from its inbound URL, so the
-     * empty-host case still verifies symmetrically when both sides agree.
-     */
-    signingHost() {
-        try {
-            return new URL(this.baseUrl).host;
-        }
-        catch {
-            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
-     * set (`Authorization: Cap …`, `X-Starfish-Sig`, `X-Starfish-Ts`,
-     * `X-Starfish-Nonce`). Empty when no provider is configured (public reads).
-     *
-     * Body bytes signed MUST equal the bytes sent on the wire — callers pass
-     * the already-serialized body string here so signing and transmission agree.
-     * The host bound into the signature is derived from `baseUrl` once per call.
+     * Pull synced data from the server.
+     * @param path - The pull endpoint path (e.g. "/pull/users/abc/settings")
+     * @param checkpoint - Only return data updated after this timestamp (0 = full pull)
      */
-    async buildAuthHeaders(method, pathAndQuery, body) {
-        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,
-        };
-        // Audience (public-link) caps bind no single subject, so the server needs
-        // the presenter's pubkey to verify the signature and check the allow-list.
-        if (pubHex !== undefined)
-            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 === undefined)
-            return null;
-        return { authorPubHex };
-    }
-    async pull(path, checkpointOrOptions) {
-        let pathAndQuery = this.applyNamespace(path);
-        let appendField;
-        if (typeof checkpointOrOptions === "number") {
-            if (checkpointOrOptions)
-                pathAndQuery += `?checkpoint=${checkpointOrOptions}`;
-        }
-        else if (checkpointOrOptions != null) {
-            // Disambiguate AppendPullOptions vs PullOptions.
-            //
-            // PullOptions are identified by the presence of `withKeyring` or
-            // `checkpoint` keys (which AppendPullOptions does not have — append
-            // uses `since`, not `checkpoint`). Anything else, including an empty
-            // `{}` object, retains the historical behavior of AppendPullOptions
-            // (extracts `data.items` with `?` query).
-            const opts = checkpointOrOptions;
-            const isPullOptions = opts.withKeyring !== undefined || opts.checkpoint !== undefined;
-            const params = new URLSearchParams();
-            if (isPullOptions) {
-                if (opts.checkpoint != null && opts.checkpoint > 0) {
-                    params.set("checkpoint", String(opts.checkpoint));
-                }
-                if (opts.withKeyring) {
-                    params.set("withKeyring", "1");
-                }
-            }
-            else {
-                appendField = opts.appendField ?? APPEND_DEFAULT_FIELD;
-                if (opts.since != null) {
-                    if (opts.since < 0)
-                        throw new Error("since must be non-negative");
-                    params.set("checkpoint", String(opts.since));
-                }
-                if (opts.last != null) {
-                    if (opts.last < 0)
-                        throw new Error("last must be non-negative");
-                    params.set("last", String(opts.last));
-                }
-            }
-            if (params.size > 0)
-                pathAndQuery += `?${params.toString()}`;
-        }
-        const url = `${this.baseUrl}${pathAndQuery}`;
-        const authHeaders = await this.buildAuthHeaders("GET", pathAndQuery, undefined);
-        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());
-        }
-        const result = await res.json();
-        if (appendField !== undefined) {
-            const list = result.data?.[appendField];
-            return (Array.isArray(list) ? list : []);
-        }
-        return result;
-    }
-    /**
-     * 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, undefined);
+    async pull(path, checkpoint) {
+        const url = checkpoint
+            ? `${this.baseUrl}${path}?checkpoint=${checkpoint}`
+            : `${this.baseUrl}${path}`;
+        const authHeaders = this.auth
+            ? await this.auth({ method: "GET", path, body: null })
+            : {};
         const res = await this.fetch(url, {
             method: "GET",
-            headers: { [HEADER_ACCEPT]: "application/json", ...authHeaders },
+            headers: { 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] ?? [];
+        return res.json();
     }
     /**
      * 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 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.
+     * @param authorSignature - Optional author signature for provenance
      * @throws {ConflictError} if the server detects a hash mismatch (409)
      */
-    async push(path, data, baseHash, author) {
+    async push(path, data, baseHash, authorSignature) {
         const body = JSON.stringify({
-            [DATA_FIELD]: data,
-            [BASE_HASH_FIELD]: baseHash,
-            ...(author && {
-                [AUTHOR_PUBKEY_FIELD]: author.authorPubkey,
-                [AUTHOR_SIGNATURE_FIELD]: author.authorSignature,
-            }),
+            data,
+            baseHash,
+            ...(authorSignature && { authorSignature }),
         });
-        const sendPath = this.applyNamespace(path);
-        const authHeaders = await this.buildAuthHeaders("POST", sendPath, body);
-        const res = await this.fetch(`${this.baseUrl}${sendPath}`, {
+        const authHeaders = this.auth
+            ? await this.auth({ method: "POST", path, body })
+            : {};
+        const res = await this.fetch(`${this.baseUrl}${path}`, {
             method: "POST",
             headers: {
-                [HEADER_CONTENT_TYPE]: "application/json",
-                [HEADER_ACCEPT]: "application/json",
+                "Content-Type": "application/json",
+                Accept: "application/json",
                 ...authHeaders,
             },
             body,
@@ -284,84 +67,23 @@ export class StarfishClient {
         }
         return res.json();
     }
-    /**
-     * Append an element to an appendOnly (`by_timestamp`) collection.
-     *
-     * Unlike {@link push}, appendOnly writes carry no hash/conflict check — an
-     * authorized append is always accepted. Each element is stored server-side as
-     * `{ts, data}` and pulls can filter by `ts` via `since`/`checkpoint`.
-     *
-     * @param path - the push endpoint (e.g. "/push/events")
-     * @param data - the element payload. For a `delegated` collection, encrypt it
-     *   first (e.g. `createKeyringEncryptor(keyring, kem).encrypt(data)`); the
-     *   server stores it opaquely and never reads it.
-     * @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
-     *   `{ 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 sendPath = this.applyNamespace(path);
-        const bodyObj = { [DATA_FIELD]: data };
-        if (opts.ts !== undefined)
-            bodyObj[TS_FIELD] = opts.ts;
-        // Author proof. Fetch the cap ONCE and reuse it for both the author
-        // signature (over the element `data`) and the request signature (over the
-        // final body) — see {@link capRequestHeaders}. The author fields are signed
-        // with the same key that authenticates the request, so a collection with
-        // `requireAuthorSignature` (the default) binds the stored element to its
-        // writer. Without a cap provider the append is sent unsigned and such a
-        // collection rejects it.
-        const capCtx = this.capProvider ? await this.capProvider.getCap() : null;
-        if (capCtx) {
-            const authorKey = this.appendAuthorKey(capCtx);
-            if (authorKey) {
-                // The signature binds the author to BOTH the element data AND the
-                // document it is written to (the storage path = `path` minus the
-                // `/push/` action prefix; the namespace lives only in the URL).
-                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 = capCtx
-            ? await this.capRequestHeaders(capCtx, "POST", sendPath, body)
-            : {};
-        const res = await this.fetch(`${this.baseUrl}${sendPath}`, {
-            method: "POST",
-            headers: {
-                [HEADER_CONTENT_TYPE]: "application/json",
-                [HEADER_ACCEPT]: "application/json",
-                ...authHeaders,
-            },
-            body,
-        });
-        if (!res.ok) {
-            throw new StarfishHttpError(res.status, await res.text());
-        }
-        return res.json();
-    }
     /**
      * Pull binary data from a blob collection.
      * Returns raw bytes with the content hash from the ETag header.
      */
     async pullBlob(path) {
-        const sendPath = this.applyNamespace(path);
-        const authHeaders = await this.buildAuthHeaders("GET", sendPath, undefined);
-        const res = await this.fetch(`${this.baseUrl}${sendPath}`, {
+        const authHeaders = this.auth
+            ? await this.auth({ method: "GET", path, body: null })
+            : {};
+        const res = await this.fetch(`${this.baseUrl}${path}`, {
             method: "GET",
-            headers: { [HEADER_ACCEPT]: "*/*", ...authHeaders },
+            headers: { 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(HEADER_CONTENT_TYPE) ?? "application/octet-stream";
+        const contentType = res.headers.get("Content-Type") ?? "application/octet-stream";
         const data = await res.arrayBuffer();
         return { data, hash: etag, contentType };
     }
@@ -370,15 +92,14 @@ export class StarfishClient {
      * Binary collections use last-write-wins (no conflict detection).
      */
     async pushBlob(path, data, contentType) {
-        // Blobs are not JSON; we leave body undefined when signing — server-side
-        // verification is expected to use a separate path for blob uploads.
-        const sendPath = this.applyNamespace(path);
-        const authHeaders = await this.buildAuthHeaders("POST", sendPath, undefined);
-        const res = await this.fetch(`${this.baseUrl}${sendPath}`, {
+        const authHeaders = this.auth
+            ? await this.auth({ method: "POST", path, body: null })
+            : {};
+        const res = await this.fetch(`${this.baseUrl}${path}`, {
             method: "POST",
             headers: {
-                [HEADER_CONTENT_TYPE]: contentType,
-                [HEADER_ACCEPT]: "application/json",
+                "Content-Type": contentType,
+                Accept: "application/json",
                 ...authHeaders,
             },
             body: data,

package/dist/crypto.js

@@ -0,0 +1,49 @@
+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

@@ -0,0 +1,41 @@
+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

@@ -0,0 +1,111 @@
+/**
+ * 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>;