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

package/dist/client.d.ts

@@ -1,5 +1,17 @@
 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. */
+export declare function stripPushPrefix(path: string): string;
 /** Result of pulling a binary blob from the server. */
 export interface BlobPullResult {
     data: ArrayBuffer;
@@ -19,6 +31,13 @@ export interface AppendPullOptions {
     since?: number;
     /** Return only the last K items (applied after `since` filter). Sent as `?last=`. */
     last?: number;
+    /** Return only the last K items. Alias of `last`; sent as `?limit=`. When both
+     *  are given, `limit` wins. */
+    limit?: number;
+    /** Explicitly fetch the whole collection (sent as `?full=true`). Mutually
+     *  exclusive with `since`/`limit`/`last` — the server requires a pull to declare
+     *  exactly one of {checkpoint, limit/last, full}. */
+    full?: boolean;
 }
 /**
  * Options for a structured (non-append) pull.
@@ -36,20 +55,55 @@ export interface PullOptions {
     /** Include the sibling `_keyring` document in the response. Defaults to false. */
     withKeyring?: boolean;
 }
+/** Per-collection result in a {@link BatchPullResult}: either the pulled
+ *  document (`data`/`hash`/`timestamp`) or a per-collection `error` string. */
+export interface BatchPullEntry {
+    data?: unknown;
+    hash?: string;
+    timestamp?: number;
+    error?: string;
+}
+/** Response of {@link StarfishClient.batchPull}: a map of requested collection
+ *  name → an ARRAY of {@link BatchPullEntry}, one per requested param-set, in
+ *  request order. A collection read with no params yields a one-element array. */
+export interface BatchPullResult {
+    collections: Record<string, BatchPullEntry[]>;
+}
+/** Options for {@link StarfishClient.batchPull}. */
+export interface BatchPullOptions {
+    /** Per-collection path params: collection name → an ARRAY of param-sets, one
+     *  per document to read from that collection, e.g.
+     *  `{ profile: [{ identity: "a" }, { identity: "b" }] }` reads two profiles in
+     *  one round-trip. Serialized to a URL-encoded JSON `params` query. The
+     *  `{identity}` param is auto-filled by the server from the authenticated
+     *  caller when a set omits it, so a single self-doc read can pass `[{}]` — or
+     *  omit the collection from `params` entirely (an unlisted collection reads one
+     *  auto-filled doc). Results come back under the same name in request order. */
+    params?: Record<string, Record<string, string>[]>;
+}
 /**
  * Low-level HTTP client for the Starfish sync protocol.
  * Handles auth headers and response parsing.
  */
 export declare class StarfishClient {
     private readonly baseUrl;
+    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
@@ -63,6 +117,18 @@ export declare class StarfishClient {
      * empty-host case still verifies symmetrically when both sides agree.
      */
     private signingHost;
+    /**
+     * 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`.
+     */
+    private applyNamespace;
     /**
      * 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
@@ -74,23 +140,78 @@ export declare class StarfishClient {
      * The host bound into the signature is derived from `baseUrl` once per call.
      */
     private buildAuthHeaders;
+    /**
+     * 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.
+     */
+    private capRequestHeaders;
+    /**
+     * 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.
+     */
+    private appendAuthorKey;
     /** Pull synced data from the server. Returns the raw `PullResult`. */
     pull(path: string, checkpoint?: number): Promise<PullResult>;
     /** Pull synced data with structured options (e.g. `{withKeyring: true}`). */
     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,
+     * 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.
+     */
+    batchPull(collections: string[], opts?: BatchPullOptions): Promise<BatchPullResult>;
+    /**
+     * 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 `[]`.
+     */
+    batchPullMany(collection: string, paramsList: Record<string, string>[]): Promise<BatchPullEntry[]>;
     /**
      * Push synced data to the server.
      * @param path - The push endpoint path (e.g. "/push/users/abc/settings")
      * @param data - The full document data to push
      * @param baseHash - Hash of the document this push is based on (null for first push)
      *
-     * v3 author fields (`authorPubkey` + `authorSignature`) live inside `data`
-     * and are produced by `SyncManager` when a `signer` is configured.
+     * v3 author proof (`authorPubkey` + `authorSignature`) is passed via `author`
+     * (produced by `SyncManager` when a `signer` is configured) and sent as
+     * top-level body siblings of `data`, where the server verifies it.
      * @throws {ConflictError} if the server detects a hash mismatch (409)
      */
-    push(path: string, data: Record<string, unknown>, baseHash: string | null): Promise<PushSuccess>;
+    push(path: string, data: Record<string, unknown>, baseHash: string | null, author?: AppendAuthor): Promise<PushSuccess>;
     /**
      * Append an element to an appendOnly (`by_timestamp`) collection.
      *
@@ -105,8 +226,10 @@ export declare class StarfishClient {
      * @param opts.ts - optional client-supplied element timestamp (ms). Must be a
      *   non-negative integer strictly greater than the latest stored element's ts
      *   (else the server responds 409). Omit to let the server assign one.
-     * @throws {StarfishHttpError} on a non-2xx response (e.g. 409 for a
-     *   non-monotonic timestamp).
+     * @throws {StarfishHttpError} on a non-2xx response — e.g. 409
+     *   `{ error: "non_monotonic_timestamp" }` for a non-monotonic timestamp, or
+     *   `{ error: "append_limit_exceeded", limit }` if the collection's `maxItems`
+     *   cap is reached (partition by a path parameter for higher volume).
      */
     append(path: string, data: Record<string, unknown>, opts?: {
         ts?: number;

package/dist/client.js

@@ -1,60 +1,277 @@
+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;
-    auth;
+    namespace;
+    capProvider;
     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(/\/$/, "");
-        this.auth = options.auth;
+        // 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.fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+        this.plugins = options.plugins ? [...options.plugins] : [];
     }
     /**
-     * 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)
+     * 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.
      */
-    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 })
-            : {};
+    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.
+     */
+    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: { Accept: "application/json", ...authHeaders },
+            headers: { [HEADER_ACCEPT]: "application/json", ...authHeaders },
         });
         if (!res.ok) {
             throw new StarfishHttpError(res.status, await res.text());
         }
-        return res.json();
+        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);
+        const res = await this.fetch(url, {
+            method: "GET",
+            headers: { [HEADER_ACCEPT]: "application/json", ...authHeaders },
+        });
+        if (!res.ok) {
+            throw new StarfishHttpError(res.status, await res.text());
+        }
+        return await res.json();
+    }
+    /**
+     * Convenience over {@link batchPull} for reading MANY documents of ONE
+     * collection in a single round-trip: pass the per-document param-sets and get
+     * back the {@link BatchPullEntry} array aligned to `paramsList` by index (each
+     * entry is `{ data, hash, timestamp }` or `{ error }`). An empty `paramsList`
+     * issues no request and returns `[]`.
+     */
+    async batchPullMany(collection, paramsList) {
+        if (paramsList.length === 0)
+            return [];
+        const res = await this.batchPull([collection], { params: { [collection]: paramsList } });
+        return res.collections[collection] ?? [];
     }
     /**
      * Push synced data to the server.
      * @param path - The push endpoint path (e.g. "/push/users/abc/settings")
      * @param data - The full document data to push
      * @param baseHash - Hash of the document this push is based on (null for first push)
-     * @param authorSignature - Optional author signature for provenance
+     *
+     * v3 author proof (`authorPubkey` + `authorSignature`) is passed via `author`
+     * (produced by `SyncManager` when a `signer` is configured) and sent as
+     * top-level body siblings of `data`, where the server verifies it.
      * @throws {ConflictError} if the server detects a hash mismatch (409)
      */
-    async push(path, data, baseHash, authorSignature) {
+    async push(path, data, baseHash, author) {
         const body = JSON.stringify({
-            data,
-            baseHash,
-            ...(authorSignature && { authorSignature }),
+            [DATA_FIELD]: data,
+            [BASE_HASH_FIELD]: baseHash,
+            ...(author && {
+                [AUTHOR_PUBKEY_FIELD]: author.authorPubkey,
+                [AUTHOR_SIGNATURE_FIELD]: author.authorSignature,
+            }),
         });
-        const authHeaders = this.auth
-            ? await this.auth({ method: "POST", path, body })
-            : {};
-        const res = await this.fetch(`${this.baseUrl}${path}`, {
+        const sendPath = this.applyNamespace(path);
+        const authHeaders = await this.buildAuthHeaders("POST", sendPath, body);
+        const res = await this.fetch(`${this.baseUrl}${sendPath}`, {
             method: "POST",
             headers: {
-                "Content-Type": "application/json",
-                Accept: "application/json",
+                [HEADER_CONTENT_TYPE]: "application/json",
+                [HEADER_ACCEPT]: "application/json",
                 ...authHeaders,
             },
             body,
@@ -67,23 +284,84 @@ 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 authHeaders = this.auth
-            ? await this.auth({ method: "GET", path, body: null })
-            : {};
-        const res = await this.fetch(`${this.baseUrl}${path}`, {
+        const sendPath = this.applyNamespace(path);
+        const authHeaders = await this.buildAuthHeaders("GET", sendPath, undefined);
+        const res = await this.fetch(`${this.baseUrl}${sendPath}`, {
             method: "GET",
-            headers: { Accept: "*/*", ...authHeaders },
+            headers: { [HEADER_ACCEPT]: "*/*", ...authHeaders },
         });
         if (!res.ok) {
             throw new StarfishHttpError(res.status, await res.text());
         }
         const etag = res.headers.get("ETag")?.replace(/"/g, "") ?? null;
-        const contentType = res.headers.get("Content-Type") ?? "application/octet-stream";
+        const contentType = res.headers.get(HEADER_CONTENT_TYPE) ?? "application/octet-stream";
         const data = await res.arrayBuffer();
         return { data, hash: etag, contentType };
     }
@@ -92,14 +370,15 @@ export class StarfishClient {
      * Binary collections use last-write-wins (no conflict detection).
      */
     async pushBlob(path, data, contentType) {
-        const authHeaders = this.auth
-            ? await this.auth({ method: "POST", path, body: null })
-            : {};
-        const res = await this.fetch(`${this.baseUrl}${path}`, {
+        // 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}`, {
             method: "POST",
             headers: {
-                "Content-Type": contentType,
-                Accept: "application/json",
+                [HEADER_CONTENT_TYPE]: contentType,
+                [HEADER_ACCEPT]: "application/json",
                 ...authHeaders,
             },
             body: data,

package/dist/config.d.ts

@@ -9,6 +9,15 @@ export interface AppendOnlyClientInfo {
     /** false = no storage write (replaces queueOnly). true/absent = append to array. */
     persist?: boolean;
 }
+/** Append-only configuration exposed via GET /config. */
+export interface AppendOnlyClientInfo {
+    /** Array field name in the stored document. Defaults to "items". */
+    field?: string;
+    /** false = no storage write (replaces queueOnly). true/absent = append to array. */
+    persist?: boolean;
+    /** When true, server validates client's baseHash against hash(lastItem). */
+    checkLastItem?: boolean;
+}
 /** Per-collection metadata returned by GET /config. */
 export interface CollectionClientInfo {
     name: string;

package/dist/directory.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Phase-2 transitional shim. Device-directory helpers now live in
+ * `@drakkar.software/starfish-identities`; member-directory helpers now live
+ * in `@drakkar.software/starfish-sharing`. Removed in Phase 3.
+ */
+export { addDeviceEntry, listDevices, removeDeviceEntry, devicesPathFor, } from "@drakkar.software/starfish-identities";
+export type { DirectoryEntry, Directory, DeviceEntry, ListDirectoryOpts, } from "@drakkar.software/starfish-identities";
+export { addMemberEntry, listMembers, removeMemberEntry, membersPathFor, } from "@drakkar.software/starfish-sharing";
+export type { MemberEntry } from "@drakkar.software/starfish-sharing";

package/dist/directory.js

@@ -0,0 +1,24 @@
+// src/directory.ts
+import {
+  addDeviceEntry,
+  listDevices,
+  removeDeviceEntry,
+  devicesPathFor
+} from "@drakkar.software/starfish-identities";
+import {
+  addMemberEntry,
+  listMembers,
+  removeMemberEntry,
+  membersPathFor
+} from "@drakkar.software/starfish-sharing";
+export {
+  addDeviceEntry,
+  addMemberEntry,
+  devicesPathFor,
+  listDevices,
+  listMembers,
+  membersPathFor,
+  removeDeviceEntry,
+  removeMemberEntry
+};
+//# sourceMappingURL=directory.js.map