@drakkar.software/starfish-client 3.0.0-alpha.1 → 3.0.0-alpha.11

package/dist/bindings/zustand.js

@@ -230,6 +230,22 @@ import { useEffect, useRef, useState, useCallback } from "react";
 
 // src/client.ts
 import {
+  AUTHOR_PUBKEY_FIELD,
+  AUTHOR_SIGNATURE_FIELD,
+  DATA_FIELD,
+  TS_FIELD,
+  BASE_HASH_FIELD,
+  PUSH_PATH_PREFIX,
+  HEADER_AUTHORIZATION,
+  HEADER_SIG,
+  HEADER_TS,
+  HEADER_NONCE,
+  HEADER_ALG,
+  HEADER_PUB,
+  HEADER_CONTENT_TYPE,
+  HEADER_ACCEPT,
+  DEFAULT_ALG,
+  signAppendAuthor,
   signRequest,
   stableStringify
 } from "@drakkar.software/starfish-protocol";
@@ -252,6 +268,9 @@ var StarfishHttpError = class extends Error {
 
 // src/client.ts
 var APPEND_DEFAULT_FIELD = "items";
+function stripPushPrefix(path) {
+  return path.startsWith(PUSH_PATH_PREFIX) ? path.slice(PUSH_PATH_PREFIX.length) : path;
+}
 function encodeCapAuth(cap) {
   const json = stableStringify(cap);
   if (typeof btoa === "function") {
@@ -263,6 +282,7 @@ function encodeCapAuth(cap) {
 }
 var StarfishClient = class {
   baseUrl;
+  namespace;
   capProvider;
   fetch;
   /**
@@ -272,6 +292,7 @@ var StarfishClient = class {
   plugins;
   constructor(options) {
     this.baseUrl = options.baseUrl.replace(/\/$/, "");
+    this.namespace = options.namespace || void 0;
     this.capProvider = options.capProvider;
     this.fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
     this.plugins = options.plugins ? [...options.plugins] : [];
@@ -295,6 +316,20 @@ var StarfishClient = class {
       return "";
     }
   }
+  /**
+   * Rewrite a request path for the configured namespace. A no-op when no
+   * namespace is set; otherwise `/{action}/…` becomes `/v1/{namespace}/{action}/…`
+   * (the `/v1` protocol-version segment is part of the namespaced route, matching
+   * the Python client and the server's namespace mount).
+   *
+   * Applied to the path used for BOTH the signature and the URL so the canonical
+   * path the client signs equals the path the server reconstructs from the URL.
+   * Covers SDK-helper-built paths too — that's the point: a namespace-unaware
+   * helper passing `/push/spaces/x/_keyring` reaches `/v1/{ns}/push/spaces/x/_keyring`.
+   */
+  applyNamespace(path) {
+    return this.namespace ? `/v1/${this.namespace}${path}` : path;
+  }
   /**
    * Build auth headers for a request. When a `capProvider` is set, signs the
    * request with the device's Ed25519 private key and returns the v3 header
@@ -306,28 +341,57 @@ var StarfishClient = class {
    * The host bound into the signature is derived from `baseUrl` once per call.
    */
   async buildAuthHeaders(method, pathAndQuery, body) {
-    if (this.capProvider) {
-      const { cap, devEdPrivHex, pubHex } = await this.capProvider.getCap();
-      const req = {
-        method,
-        pathAndQuery,
-        body,
-        host: this.signingHost()
-      };
-      const { sig, ts, nonce } = await signRequest(req, devEdPrivHex);
-      const headers = {
-        Authorization: `Cap ${encodeCapAuth(cap)}`,
-        "X-Starfish-Sig": sig,
-        "X-Starfish-Ts": String(ts),
-        "X-Starfish-Nonce": nonce
-      };
-      if (pubHex !== void 0) headers["X-Starfish-Pub"] = pubHex;
-      return headers;
-    }
-    return {};
+    if (!this.capProvider) return {};
+    const capCtx = await this.capProvider.getCap();
+    return this.capRequestHeaders(capCtx, method, pathAndQuery, body);
+  }
+  /**
+   * Build the request-signing headers from an ALREADY-fetched cap context. Split
+   * out of {@link buildAuthHeaders} so {@link append} can fetch the cap once and
+   * reuse it for BOTH the author signature (over the element data) and the
+   * request signature (over the body), without redeeming the cap twice — a
+   * second `getCap()` could rotate keys and break the `authorPubkey ===
+   * presenter` bind the server checks.
+   */
+  async capRequestHeaders(capCtx, method, pathAndQuery, body) {
+    const { cap, devEdPrivHex, pubHex, presenterAlg } = capCtx;
+    const req = {
+      method,
+      pathAndQuery,
+      body,
+      host: this.signingHost()
+    };
+    const signAlg = cap.kind === "audience" ? presenterAlg ?? DEFAULT_ALG : cap.subAlg ?? cap.issAlg;
+    const { alg, sig, ts, nonce } = await signRequest(req, devEdPrivHex, {
+      alg: signAlg
+    });
+    const headers = {
+      [HEADER_AUTHORIZATION]: `Cap ${encodeCapAuth(cap)}`,
+      [HEADER_SIG]: sig,
+      [HEADER_TS]: String(ts),
+      [HEADER_NONCE]: nonce,
+      [HEADER_ALG]: alg
+    };
+    if (pubHex !== void 0) headers[HEADER_PUB] = pubHex;
+    return headers;
+  }
+  /**
+   * Resolve the author public key to attach to a signed append: the redeemer's
+   * `pubHex` for an audience cap, else the cert subject `cap.sub` for a
+   * device/member cap. This is the SAME key that signs the request, so a server
+   * enforcing author proof can bind the stored element to its writer. Returns
+   * undefined only for a (malformed) cap with neither — the append then goes
+   * unsigned and a server requiring signatures rejects it.
+   */
+  appendAuthorKey(capCtx) {
+    const { cap, pubHex, presenterAlg } = capCtx;
+    const authorPubHex = pubHex ?? cap.sub;
+    if (authorPubHex === void 0) return null;
+    const signAlg = cap.kind === "audience" ? presenterAlg ?? DEFAULT_ALG : cap.subAlg ?? cap.issAlg;
+    return { authorPubHex, signAlg };
   }
   async pull(path, checkpointOrOptions) {
-    let pathAndQuery = path;
+    let pathAndQuery = this.applyNamespace(path);
     let appendField;
     if (typeof checkpointOrOptions === "number") {
       if (checkpointOrOptions) pathAndQuery += `?checkpoint=${checkpointOrOptions}`;
@@ -359,7 +423,7 @@ var StarfishClient = class {
     const authHeaders = await this.buildAuthHeaders("GET", pathAndQuery, void 0);
     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());
@@ -371,27 +435,78 @@ var StarfishClient = class {
     }
     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, void 0);
+    const res = await this.fetch(url, {
+      method: "GET",
+      headers: { [HEADER_ACCEPT]: "application/json", ...authHeaders }
+    });
+    if (!res.ok) {
+      throw new StarfishHttpError(res.status, await res.text());
+    }
+    return await res.json();
+  }
+  /**
+   * Convenience over {@link batchPull} for reading MANY documents of ONE
+   * collection in a single round-trip: pass the per-document param-sets and get
+   * back the {@link BatchPullEntry} array aligned to `paramsList` by index (each
+   * entry is `{ data, hash, timestamp }` or `{ error }`). An empty `paramsList`
+   * issues no request and returns `[]`.
+   */
+  async batchPullMany(collection, paramsList) {
+    if (paramsList.length === 0) return [];
+    const res = await this.batchPull([collection], { params: { [collection]: paramsList } });
+    return res.collections[collection] ?? [];
+  }
   /**
    * Push synced data to the server.
    * @param path - The push endpoint path (e.g. "/push/users/abc/settings")
    * @param data - The full document data to push
    * @param baseHash - Hash of the document this push is based on (null for first push)
    *
-   * v3 author fields (`authorPubkey` + `authorSignature`) live inside `data`
-   * and are produced by `SyncManager` when a `signer` is configured.
+   * v3 author proof (`authorPubkey` + `authorSignature`) is passed via `author`
+   * (produced by `SyncManager` when a `signer` is configured) and sent as
+   * top-level body siblings of `data`, where the server verifies it.
    * @throws {ConflictError} if the server detects a hash mismatch (409)
    */
-  async push(path, data, baseHash) {
+  async push(path, data, baseHash, author) {
     const body = JSON.stringify({
-      data,
-      baseHash
+      [DATA_FIELD]: data,
+      [BASE_HASH_FIELD]: baseHash,
+      ...author && {
+        [AUTHOR_PUBKEY_FIELD]: author.authorPubkey,
+        [AUTHOR_SIGNATURE_FIELD]: author.authorSignature
+      }
     });
-    const authHeaders = await this.buildAuthHeaders("POST", path, body);
-    const res = await this.fetch(`${this.baseUrl}${path}`, {
+    const sendPath = this.applyNamespace(path);
+    const authHeaders = await this.buildAuthHeaders("POST", sendPath, body);
+    const res = await this.fetch(`${this.baseUrl}${sendPath}`, {
       method: "POST",
       headers: {
-        "Content-Type": "application/json",
-        Accept: "application/json",
+        [HEADER_CONTENT_TYPE]: "application/json",
+        [HEADER_ACCEPT]: "application/json",
         ...authHeaders
       },
       body
@@ -404,21 +519,77 @@ var StarfishClient = class {
     }
     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 !== void 0) bodyObj[TS_FIELD] = opts.ts;
+    const capCtx = this.capProvider ? await this.capProvider.getCap() : null;
+    if (capCtx) {
+      const authorKey = this.appendAuthorKey(capCtx);
+      if (authorKey) {
+        const documentKey = stripPushPrefix(path);
+        const { authorPubkey, authorSignature } = signAppendAuthor(
+          documentKey,
+          data,
+          authorKey.authorPubHex,
+          capCtx.devEdPrivHex,
+          authorKey.signAlg
+        );
+        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 = await this.buildAuthHeaders("GET", path, void 0);
-    const res = await this.fetch(`${this.baseUrl}${path}`, {
+    const sendPath = this.applyNamespace(path);
+    const authHeaders = await this.buildAuthHeaders("GET", sendPath, void 0);
+    const res = await this.fetch(`${this.baseUrl}${sendPath}`, {
       method: "GET",
-      headers: { Accept: "*/*", ...authHeaders }
+      headers: { [HEADER_ACCEPT]: "*/*", ...authHeaders }
     });
     if (!res.ok) {
       throw new StarfishHttpError(res.status, await res.text());
     }
     const etag = res.headers.get("ETag")?.replace(/"/g, "") ?? null;
-    const contentType = res.headers.get("Content-Type") ?? "application/octet-stream";
+    const contentType = res.headers.get(HEADER_CONTENT_TYPE) ?? "application/octet-stream";
     const data = await res.arrayBuffer();
     return { data, hash: etag, contentType };
   }
@@ -427,12 +598,13 @@ var StarfishClient = class {
    * Binary collections use last-write-wins (no conflict detection).
    */
   async pushBlob(path, data, contentType) {
-    const authHeaders = await this.buildAuthHeaders("POST", path, void 0);
-    const res = await this.fetch(`${this.baseUrl}${path}`, {
+    const sendPath = this.applyNamespace(path);
+    const authHeaders = await this.buildAuthHeaders("POST", sendPath, void 0);
+    const res = await this.fetch(`${this.baseUrl}${sendPath}`, {
       method: "POST",
       headers: {
-        "Content-Type": contentType,
-        Accept: "application/json",
+        [HEADER_CONTENT_TYPE]: contentType,
+        [HEADER_ACCEPT]: "application/json",
         ...authHeaders
       },
       body: data
@@ -445,7 +617,13 @@ var StarfishClient = class {
 };
 
 // src/sync.ts
-import { deepMerge, getBase64, stableStringify as stableStringify2 } from "@drakkar.software/starfish-protocol";
+import {
+  AUTHOR_PUBKEY_FIELD as AUTHOR_PUBKEY_FIELD2,
+  AUTHOR_SIGNATURE_FIELD as AUTHOR_SIGNATURE_FIELD2,
+  deepMerge,
+  docAuthorCanonicalInput,
+  getBase64
+} from "@drakkar.software/starfish-protocol";
 
 // src/validate.ts
 var ValidationError = class extends Error {
@@ -550,23 +728,24 @@ var SyncManager = class {
       try {
         const sealed = this.encryptor ? await this.encryptor.encrypt(pendingData) : pendingData;
         if (this.aborted) throw new AbortError();
-        let payload = sealed;
+        let author;
         if (this.signer) {
           const { devEdPubHex, sign } = await this.signer.getSigner();
           if (this.aborted) throw new AbortError();
-          const canonical = stableStringify2(sealed);
+          const documentKey = stripPushPrefix(this.pushPath);
+          const canonical = docAuthorCanonicalInput(documentKey, sealed);
           const sigBytes = await sign(new TextEncoder().encode(canonical));
           if (this.aborted) throw new AbortError();
-          payload = {
-            ...sealed,
-            authorPubkey: devEdPubHex,
-            authorSignature: getBase64().encode(sigBytes)
+          author = {
+            [AUTHOR_PUBKEY_FIELD2]: devEdPubHex,
+            [AUTHOR_SIGNATURE_FIELD2]: getBase64().encode(sigBytes)
           };
         }
         const result = await this.client.push(
           this.pushPath,
-          payload,
-          this.lastHash
+          sealed,
+          this.lastHash,
+          author
         );
         if (this.aborted) throw new AbortError();
         this.lastHash = result.hash;
@@ -840,6 +1019,7 @@ function useSyncInit(config) {
     }
     const client = new StarfishClient({
       baseUrl: config.serverUrl,
+      namespace: config.namespace,
       capProvider: config.capProvider,
       fetch: config.fetch
     });
@@ -883,16 +1063,101 @@ function useSyncInit(config) {
   ]);
   return store;
 }
+function createStarfishLog(options) {
+  const { cursor } = options;
+  const storeCreator = (rawSet, get) => {
+    const set = rawSet;
+    return {
+      // Seed from the cursor so a warm-started cursor's items show immediately.
+      items: cursor.getItems(),
+      loading: false,
+      online: true,
+      error: null,
+      checkpoint: cursor.getCheckpoint(),
+      pull: async () => {
+        if (get().loading) return [];
+        set({ loading: true, error: null }, false, "log/pull/start");
+        try {
+          const batch = await cursor.pull();
+          set(
+            { items: cursor.getItems(), checkpoint: cursor.getCheckpoint(), loading: false },
+            false,
+            "log/pull/success"
+          );
+          return batch;
+        } catch (err) {
+          set({ loading: false, error: err instanceof Error ? err.message : String(err) }, false, "log/pull/error");
+          return [];
+        }
+      },
+      setOnline: (online) => {
+        set({ online }, false, "log/setOnline");
+      }
+    };
+  };
+  const withSelector = subscribeWithSelector(storeCreator);
+  return createStore()(
+    options.devtools ? options.devtools(withSelector) : withSelector
+  );
+}
+function deriveLogStatus(state) {
+  if (!state.online) return "offline";
+  if (state.error) return "error";
+  if (state.loading) return "loading";
+  return "idle";
+}
+function useStarfishLog(store) {
+  return useStore(store);
+}
+function useStarfishLogItems(store, selector) {
+  return useStore(
+    store,
+    (state) => selector ? selector(state.items) : state.items
+  );
+}
+function useLogStatus(store) {
+  return useStore(store, deriveLogStatus);
+}
+function subscribeLogStatus(store, callback) {
+  let prev = deriveLogStatus(store.getState());
+  callback(prev);
+  return store.subscribe((state) => {
+    const next = deriveLogStatus(state);
+    if (next !== prev) {
+      prev = next;
+      callback(next);
+    }
+  });
+}
+function useLogConnectivity(store) {
+  useEffect(() => {
+    const handleOnline = () => store.getState().setOnline(true);
+    const handleOffline = () => store.getState().setOnline(false);
+    window.addEventListener("online", handleOnline);
+    window.addEventListener("offline", handleOffline);
+    return () => {
+      window.removeEventListener("online", handleOnline);
+      window.removeEventListener("offline", handleOffline);
+    };
+  }, [store]);
+}
 export {
   aggregateSyncStatus,
+  createStarfishLog,
   createStarfishStore,
+  deriveLogStatus,
   deriveSyncStatus,
+  subscribeLogStatus,
   subscribeSyncStatus,
   useConnectivity,
   useCrossTabSync,
   useLastSynced,
+  useLogConnectivity,
+  useLogStatus,
   useStarfish,
   useStarfishData,
+  useStarfishLog,
+  useStarfishLogItems,
   useSyncInit,
   useSyncStatus
 };