@drakkar.software/starfish-client 3.0.0-alpha.5 → 3.0.0-alpha.50

package/dist/blob-seal.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Generic client-side blob sealing helpers.
+ *
+ * Provides a structural {@link ByteSealer} interface and two convenience
+ * functions — {@link sealAndPushBlob} / {@link pullAndOpenBlob} — that wire a
+ * sealer (e.g. a `KeyringEncryptor` from `@drakkar.software/starfish-keyring`)
+ * into the binary blob transport (`StarfishClient.pushBlob` / `pullBlob`).
+ *
+ * The server collection must use `encryption: "none"` — all sealing and
+ * unsealing happens client-side. The server stores and returns opaque
+ * ciphertext.
+ *
+ * **AAD (Additional Authenticated Data):** callers MUST pass a stable, unique
+ * `aad` string (typically the storage path, e.g. the value returned by a
+ * `*Name(spaceId, blobId)` helper). The AAD is bound into the AES-GCM tag
+ * and prevents ciphertext relocation: a blob sealed with AAD `"path/a"` cannot
+ * be opened as `"path/b"`. When `aad` is omitted, the document key (path with
+ * the `/push/` or `/pull/` action prefix stripped) is used as a fallback —
+ * the same key is derived on both the seal and open side so round-trips work
+ * without an explicit `aad`. **Callers with existing sealed data MUST pass the
+ * same explicit AAD they used when sealing** to preserve back-compat.
+ *
+ * @module blob-seal
+ */
+import type { StarfishClient } from "./client.js";
+import type { BlobPushResult } from "./client.js";
+/**
+ * Structural interface satisfied by a `KeyringEncryptor` from
+ * `@drakkar.software/starfish-keyring` (and any compatible cipher adapter).
+ *
+ * Implementations must use AES-256-GCM and bind the `aad` into the ciphertext
+ * tag so that relocation is detected on open.
+ */
+export interface ByteSealer {
+    /**
+     * Encrypt `bytes` and return the sealed ciphertext.
+     * @param bytes - Plaintext bytes to seal.
+     * @param aad   - Additional authenticated data bound into the ciphertext tag.
+     *                Must be the same string passed to {@link openBytes}.
+     */
+    sealBytes(bytes: Uint8Array, aad?: string): Promise<Uint8Array>;
+    /**
+     * Decrypt a sealed blob back to plaintext bytes.
+     * @param blob - Ciphertext produced by {@link sealBytes}.
+     * @param aad  - Same AAD string that was used during sealing.
+     * @throws if the ciphertext has been tampered with or the AAD does not match.
+     */
+    openBytes(blob: Uint8Array, aad?: string): Promise<Uint8Array>;
+}
+/** Options for {@link sealAndPushBlob}. */
+export interface SealAndPushBlobOptions {
+    /**
+     * Additional authenticated data bound into the AES-GCM ciphertext tag.
+     *
+     * Callers with existing sealed data MUST pass the **same explicit AAD** they
+     * used when originally sealing so that already-stored blobs can still be
+     * opened.  When omitted, the document key (push path with the `/push/`
+     * prefix stripped) is used as a fallback.
+     */
+    aad?: string;
+    /**
+     * When set, throws a `RangeError` before sealing if `bytes.length` exceeds
+     * this limit.  Checked against the **plaintext** size (before sealing adds
+     * overhead).
+     *
+     * Note: AES-256-GCM sealing adds ~28 bytes of overhead (12-byte nonce +
+     * 16-byte tag). If you are mirroring the server's `maxBodyBytes` limit,
+     * subtract at least 28 to ensure the sealed ciphertext also fits.
+     */
+    maxBytes?: number;
+}
+/**
+ * Seal `bytes` with `sealer` (AAD bound to the storage path) and push the
+ * resulting ciphertext to the server via `client.pushBlob`.
+ *
+ * Sealed bytes are always pushed with `Content-Type: application/octet-stream`,
+ * matching the `allowedMimeTypes` of a {@link createSealedParquetCollection} preset.
+ *
+ * @param client  - A connected `StarfishClient`.
+ * @param sealer  - A `ByteSealer` (e.g. `KeyringEncryptor` from `starfish-keyring`).
+ * @param path    - Push path (starts with `/push/…`).
+ * @param bytes   - Plaintext bytes to seal and upload.
+ * @param opts    - See {@link SealAndPushBlobOptions}.
+ * @returns The server's push result (hash).
+ *
+ * @throws {RangeError} if `opts.maxBytes` is set and `bytes.length` exceeds it.
+ *
+ * @example
+ * ```ts
+ * const result = await sealAndPushBlob(client, enc, objectBlobPush(spaceId, blobId), bytes, {
+ *   aad: objectBlobName(spaceId, blobId),
+ * })
+ * ```
+ */
+export declare function sealAndPushBlob(client: StarfishClient, sealer: ByteSealer, path: string, bytes: Uint8Array, opts?: SealAndPushBlobOptions): Promise<BlobPushResult>;
+/** Options for {@link pullAndOpenBlob}. */
+export interface PullAndOpenBlobOptions {
+    /**
+     * Additional authenticated data — must match the AAD used when sealing.
+     * Defaults to the document key (pull path with the `/pull/` prefix stripped),
+     * which matches the default AAD used by {@link sealAndPushBlob}.
+     */
+    aad?: string;
+}
+/**
+ * Pull a sealed blob from the server and unseal it with `sealer`.
+ *
+ * @param client - A connected `StarfishClient`.
+ * @param sealer - A `ByteSealer` that can open the sealed bytes.
+ * @param path   - Pull path (starts with `/pull/…` or is a bare document key).
+ * @param opts   - See {@link PullAndOpenBlobOptions}.
+ * @returns The original plaintext bytes.
+ *
+ * @throws if the ciphertext is invalid, tampered with, or the AAD does not match.
+ *
+ * @example
+ * ```ts
+ * const bytes = await pullAndOpenBlob(client, enc, objectBlobPull(spaceId, blobId), {
+ *   aad: objectBlobName(spaceId, blobId),
+ * })
+ * ```
+ */
+export declare function pullAndOpenBlob(client: StarfishClient, sealer: ByteSealer, path: string, opts?: PullAndOpenBlobOptions): Promise<Uint8Array>;

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.
@@ -35,6 +54,66 @@ export interface PullOptions {
     checkpoint?: number;
     /** Include the sibling `_keyring` document in the response. Defaults to false. */
     withKeyring?: boolean;
+    /**
+     * Serve the last-synced cached snapshot immediately (tagged via
+     * {@link pullWasFromCache}) and revalidate in the background. Requires a
+     * {@link StarfishClientOptions.cache} to be configured; without one the option
+     * is a no-op and the pull goes to the network as usual.
+     *
+     * On a cache hit: returns the stale snapshot at once, kicks a background fetch,
+     * and on success writes the fresh snapshot to cache and fires
+     * {@link StarfishClientOptions.onRevalidated}. Uses the same dedup set as the
+     * {@link StarfishClientOptions.cacheFallbackStatuses} revalidation path — a
+     * concurrent error-triggered loop for the same document is not duplicated.
+     *
+     * On a cache miss: falls through to the normal network-first pull unchanged.
+     */
+    staleWhileRevalidate?: 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>[]>;
+    /**
+     * Per-collection append options, index-aligned to `params`. Makes the batch
+     * request **append/checkpoint-aware**: each entry returns the bounded tail of
+     * that collection's append-only log rather than the full document.
+     *
+     * Serialized as URL-encoded JSON alongside `params`. Server ignores it for
+     * collections that are not append-only (returns `{ error: "append_params_not_supported" }`
+     * for those entries). `full` is disallowed in batch (`full_not_allowed` per entry).
+     *
+     * Example — read the last 5 events for two rooms and the newest item for a third:
+     * ```ts
+     * await client.batchPull(["events"], {
+     *   params: { events: [{ room: "a" }, { room: "b" }, { room: "c" }] },
+     *   appendParams: { events: [{ last: 5 }, { last: 5 }, { last: 1 }] },
+     * })
+     * ```
+     * Each `data[appendField]` in the result is the filtered array for that entry.
+     */
+    appendParams?: Record<string, AppendPullOptions[]>;
 }
 /**
  * Low-level HTTP client for the Starfish sync protocol.
@@ -45,12 +124,29 @@ export declare class StarfishClient {
     private readonly namespace?;
     private readonly capProvider?;
     private readonly fetch;
+    private readonly cache?;
+    private readonly cacheMaxAgeMs?;
+    private readonly cacheFallbackStatuses?;
+    private readonly onRevalidated?;
+    private readonly revalidating;
+    /**
+     * In-memory mirror of the latest document timestamp written to each cache
+     * key via {@link writeCache}. Updated synchronously so {@link revalidateLoop}
+     * can guard against stale overwrites without an extra async cache read.
+     */
+    private readonly latestCacheTimestamp;
     /**
      * 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
@@ -87,23 +183,131 @@ 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[]>;
+    /**
+     * Write a pull snapshot to the cache. Fire-and-forget; errors are swallowed
+     * so a failing cache never blocks the caller. No-op when no cache is configured.
+     */
+    private writeCache;
+    /** Build the URL + auth headers for one revalidation GET. Shared between
+     *  {@link pull} and {@link revalidateLoop} to avoid duplicated fetch setup. */
+    private revalidateFetch;
+    /**
+     * Deduplicated fire-and-forget: starts one revalidation loop per cacheKey.
+     * Used by both the {@link cacheFallbackStatuses} error path (delayed first
+     * attempt, honoring `Retry-After`) and the {@link PullOptions.staleWhileRevalidate}
+     * read path (`immediate: true` — no initial delay on the first attempt). The
+     * `revalidating` set deduplicates across both triggers so a concurrent
+     * error-triggered loop and an SWR-on-read loop for the same key collapse to one.
+     */
+    private scheduleRevalidate;
+    /**
+     * Background revalidation loop shared by both {@link cacheFallbackStatuses}
+     * hits and {@link PullOptions.staleWhileRevalidate} reads.
+     *
+     * Retries (honoring `Retry-After`) up to {@link MAX_REVALIDATE_ATTEMPTS} times.
+     * When `immediate` is true the first attempt fires without any initial delay
+     * (SWR-on-read path). On a live 2xx the fresh snapshot is written to cache and
+     * {@link onRevalidated} fires. Stops early on a non-fallback status (403/404).
+     */
+    private revalidateLoop;
+    /**
+     * 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}.
+     *
+     * Pass `appendParams` per entry for append-only bounded-tail reads (see {@link batchPullManyAppend}).
+     */
+    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[]>;
+    /**
+     * Convenience over {@link batchPull} for reading append-only bounded tails from
+     * MANY entries of ONE collection in a single round-trip.
+     *
+     * Each request in `requests` carries optional `params` (path params) and
+     * `options` (append bounds: `since`/`last`/`limit`/`appendField`). An empty
+     * `requests` issues no request and returns `[]`.
+     *
+     * Returns an array aligned to `requests` by index. Each element is either:
+     * - the filtered array `T[]` extracted from `entry.data[appendField]`, or
+     * - `{ error: string }` if the server returned a per-entry error.
+     *
+     * The `appendField` used for extraction defaults to `"items"` and can be
+     * overridden per request via `options.appendField`.
+     *
+     * The `appendField` option is client-side only (used for result extraction, not sent to the server).
+     * It must match the collection's server-configured append field and defaults to `"items"`.
+     *
+     * Note: `full: true` is not supported in batch and is rejected client-side
+     * before the request is sent.
+     */
+    batchPullManyAppend<T = unknown>(collection: string, requests: {
+        params?: Record<string, string>;
+        options: AppendPullOptions;
+    }[]): Promise<(T[] | {
+        error: string;
+    })[]>;
     /**
      * 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.
      *
@@ -118,12 +322,44 @@ 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;
     }): Promise<PushSuccess>;
+    /**
+     * Append one element to a **public-write** append-only collection with an
+     * Ed25519 author proof but **no cap `Authorization` header**.
+     *
+     * Unlike {@link append}, which always attaches a cap-signed `Authorization`
+     * header from the configured `capProvider`, this method signs only the
+     * append-author proof (binding the element to the writer's Ed25519 key) and
+     * sends the request without authentication headers. This is required for
+     * collections with `writeRoles: ["public"]` — the server's cap-scope check
+     * would reject a request carrying a cap whose scope does not cover the path.
+     *
+     * Typical use-case: writing a sealed invitation to another user's
+     * public-write inbox collection without needing a cap scoped to the
+     * recipient's namespace. The author proof is optional on the server side
+     * (`requireAuthorSignature: false` for a public inbox), but signing anyway
+     * binds the stored element to the sender's Ed25519 key for verification in
+     * the receive path.
+     *
+     * The element is sent as `{ data, authorPubkey, authorSignature }`.
+     *
+     * @param path    The push path, e.g. `/push/inbox/{userId}/{shard}`.
+     * @param element The JSON element to append.
+     * @param signer  The sender's Ed25519 keypair (signs the author proof).
+     *
+     * @throws {AppendHttpError} on a non-2xx response.
+     */
+    appendAnonymous(path: string, element: Record<string, unknown>, signer: {
+        edPubHex: string;
+        edPrivHex: string;
+    }): Promise<void>;
     /**
      * Pull binary data from a blob collection.
      * Returns raw bytes with the content hash from the ETag header.
@@ -134,4 +370,33 @@ export declare class StarfishClient {
      * Binary collections use last-write-wins (no conflict detection).
      */
     pushBlob(path: string, data: ArrayBuffer | Uint8Array | Blob, contentType: string): Promise<BlobPushResult>;
+    /**
+     * Push an Apache Parquet file to a Parquet collection.
+     *
+     * Thin wrapper over {@link pushBlob} that fixes `Content-Type` to
+     * `application/vnd.apache.parquet` so the S3 object is tagged correctly
+     * for DuckDB and CDN consumption.
+     *
+     * @example
+     * ```ts
+     * const parquetBytes = await generateParquet(rows)
+     * const result = await client.pushParquet("/push/analytics/alice/q1.parquet", parquetBytes)
+     * console.log("stored hash:", result.hash)
+     * ```
+     */
+    pushParquet(path: string, data: ArrayBuffer | Uint8Array | Blob): Promise<BlobPushResult>;
+    /**
+     * Pull an Apache Parquet file from a Parquet collection.
+     *
+     * Thin wrapper over {@link pullBlob} for API symmetry with
+     * {@link pushParquet}.
+     *
+     * @example
+     * ```ts
+     * const result = await client.pullParquet("/pull/analytics/alice/q1.parquet")
+     * // result.data        → ArrayBuffer
+     * // result.contentType → "application/vnd.apache.parquet"
+     * ```
+     */
+    pullParquet(path: string): Promise<BlobPullResult>;
 }