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

package/dist/append.d.ts

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

package/dist/bindings/broadcast.d.ts

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

package/dist/bindings/broadcast.js

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

package/dist/bindings/react.d.ts

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

package/dist/bindings/react.js

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

package/dist/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 });
+            }
+        },
+    };
+}