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

package/dist/_crypto_helpers.d.ts

@@ -0,0 +1,4 @@
+export declare function hkdfBytes(ikm: Uint8Array, salt: Uint8Array, info: Uint8Array, lengthBytes?: number): Promise<Uint8Array>;
+export declare function bytesToHex(bytes: Uint8Array): string;
+export declare function hexToBytes(hex: string): Uint8Array;
+export declare function concat(...parts: Uint8Array[]): Uint8Array;

package/dist/append-log.js

@@ -0,0 +1,267 @@
+import { verifyAppendAuthor, } from "@drakkar.software/starfish-protocol";
+/** The `/pull/` action prefix; mirrors `PUSH_PATH_PREFIX` for the read side. */
+const PULL_PATH_PREFIX = "/pull/";
+/** The storage `documentKey` for a pull `path`: the path with the `/pull/`
+ *  action prefix stripped (the namespace lives only in the URL). The author
+ *  signature binds to this key, so a reader re-derives it the same way the
+ *  writer did from `/push/…`. */
+function stripPullPrefix(path) {
+    return path.startsWith(PULL_PATH_PREFIX) ? path.slice(PULL_PATH_PREFIX.length) : path;
+}
+/** Thrown when an append element's author signature fails verification. */
+export class AppendAuthorError extends Error {
+    ts;
+    constructor(ts) {
+        super(`append element author verification failed (ts=${ts})`);
+        this.ts = ts;
+        this.name = "AppendAuthorError";
+    }
+}
+/** Largest `ts` among `items`, or `0` when empty. The checkpoint for an
+ *  append-only log is exactly this — the server returns elements with
+ *  `ts > checkpoint`, and element timestamps are strictly increasing. */
+export function checkpointOf(items) {
+    let max = 0;
+    for (const it of items)
+        if (it.ts > max)
+            max = it.ts;
+    return max;
+}
+/** Copy the optional author fields from `src` onto a fresh element with `data`. */
+function withAuthor(ts, data, src) {
+    const out = { ts, data };
+    if (src.authorPubkey !== undefined)
+        out.authorPubkey = src.authorPubkey;
+    if (src.authorSignature !== undefined)
+        out.authorSignature = src.authorSignature;
+    return out;
+}
+/**
+ * A stateful cursor over an append-only collection. It owns the accumulated
+ * array of elements and pulls only what is new: each {@link pull} derives the
+ * checkpoint from the last element it holds and asks the server for elements
+ * with a greater `ts`.
+ *
+ * This is the incremental, stateful counterpart to the deliberately stateless
+ * `client.pull(path, { appendField, since })`, and the sibling of
+ * {@link SyncManager} for append-only logs (no merge / push-conflict
+ * machinery — a log only grows).
+ *
+ * The cursor accumulates every pulled element in memory; for an unboundedly
+ * large log, pull a bounded window with raw `client.pull(path, { last })` instead.
+ *
+ * Cold start (nothing persisted) — first `pull()` fetches the whole collection:
+ * ```ts
+ * const log = new AppendLogCursor({ client, pullPath: "/pull/events" })
+ * const all = await log.pull()
+ * ```
+ * Warm start (resume from persisted data) — first `pull()` fetches only newer
+ * elements; persistence is a round-trip of `getItems()`:
+ * ```ts
+ * const log = new AppendLogCursor({ client, pullPath: "/pull/events",
+ *   initialItems: await store.load() })
+ * const fresh = await log.pull()
+ * await store.save(log.getItems())
+ * ```
+ * Warm start for an **E2EE** log — persist ciphertext, render decrypted:
+ * ```ts
+ * const log = new AppendLogCursor({ client, pullPath: "/pull/streamchat",
+ *   encryptor, persistEncrypted: true, onElementError: "skip",
+ *   initialItems: await store.load() })           // ciphertext from disk
+ * const history = await log.getDecryptedItems()    // render persisted history
+ * const fresh = await log.pull()                   // decrypted delta
+ * await store.save(log.getItems())                 // ciphertext back to disk
+ * ```
+ */
+export class AppendLogCursor {
+    client;
+    pullPath;
+    appendField;
+    encryptor;
+    verifyAuthor;
+    onElementError;
+    persistEncrypted;
+    documentKey;
+    logger;
+    loggerName;
+    items;
+    lastCheckpoint;
+    /** Tail of the serialized pull chain. Concurrent `pull()` calls queue behind
+     *  it so each runs against the checkpoint the previous one advanced — no two
+     *  overlapping fetches read the same checkpoint and double-append a window. */
+    pullChain = Promise.resolve();
+    constructor(options) {
+        this.client = options.client;
+        this.pullPath = options.pullPath;
+        this.appendField = options.appendField ?? "items";
+        this.encryptor = options.encryptor;
+        this.verifyAuthor = options.verifyAuthor;
+        this.onElementError = options.onElementError ?? "throw";
+        this.persistEncrypted = options.persistEncrypted ?? false;
+        this.documentKey = stripPullPrefix(options.pullPath);
+        this.logger = options.logger;
+        this.loggerName =
+            options.loggerName ?? options.pullPath.split("/").filter(Boolean).pop() ?? options.pullPath;
+        const seed = options.initialItems ?? [];
+        const seedCheckpoint = checkpointOf(seed);
+        if (options.since != null) {
+            if (options.since < 0)
+                throw new Error("since must be non-negative");
+            if (options.since < seedCheckpoint) {
+                throw new Error("since must be >= the max ts of initialItems");
+            }
+            this.lastCheckpoint = options.since;
+        }
+        else {
+            this.lastCheckpoint = seedCheckpoint;
+        }
+        this.items = [...seed];
+    }
+    /**
+     * Fetch elements newer than the current checkpoint, verify + decrypt them,
+     * append them to the local log, and return ONLY the newly-fetched batch
+     * (decrypted when an `encryptor` is set).
+     *
+     * Atomic under `onElementError: "throw"` (the default): the batch is fully
+     * verified and decrypted into a local before any state mutation, so a
+     * verify/decrypt failure throws without advancing the checkpoint past elements
+     * that could never be re-fetched. Under `"skip"`, a failing element is dropped
+     * from the returned batch but the checkpoint still advances past it.
+     *
+     * Safe to call concurrently: overlapping calls are serialized internally, so
+     * each runs against the checkpoint the previous one advanced (no double-fetch
+     * of the same window). The next pull after one completes will pick up anything
+     * that arrived in between.
+     */
+    async pull() {
+        // Chain onto the previous pull (whether it resolved or rejected) so calls
+        // run one-at-a-time against the latest checkpoint. `pullChain` swallows
+        // outcomes to stay alive; the caller still sees this call's real result.
+        const run = this.pullChain.then(() => this.doPull(), () => this.doPull());
+        this.pullChain = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    async doPull() {
+        this.logger?.pullStart(this.loggerName);
+        const start = performance.now();
+        try {
+            const since = this.lastCheckpoint;
+            // Omit `since` on cold start so the request carries no `?checkpoint=`.
+            const opts = since > 0 ? { appendField: this.appendField, since } : { appendField: this.appendField };
+            const raw = await this.client.pull(this.pullPath, opts);
+            const batch = []; // decrypted, returned to the caller
+            const stored = []; // what we keep in `items` (cipher- or plaintext)
+            let maxTs = since;
+            let skipped = 0;
+            for (const el of raw) {
+                // Defensive: guard a misbehaving/mocked server from making us
+                // double-append a held element. Gated on `since > 0` to mirror the
+                // server (which only filters when checkpoint > 0): on a cold start
+                // `since` is 0 and we must NOT drop a legitimate `ts: 0` first element.
+                if (since > 0 && el.ts <= since)
+                    continue;
+                // Advance past every windowed element BEFORE verify/decrypt so a skipped
+                // element still moves the checkpoint and is never re-fetched.
+                if (el.ts > maxTs)
+                    maxTs = el.ts;
+                let decrypted = null;
+                try {
+                    this.verifyOne(el);
+                    const data = this.encryptor ? await this.encryptor.decrypt(el.data) : el.data;
+                    decrypted = withAuthor(el.ts, data, el);
+                }
+                catch (err) {
+                    // "throw" rethrows here, before any state mutation below — atomic.
+                    if (this.onElementError !== "skip")
+                        throw err;
+                    skipped++;
+                }
+                if (this.persistEncrypted) {
+                    // Keep the original ciphertext envelope (even for a skipped element:
+                    // it is valid data we simply cannot read now — a later key might).
+                    stored.push(withAuthor(el.ts, el.data, el));
+                }
+                else if (decrypted) {
+                    stored.push(decrypted);
+                }
+                if (decrypted)
+                    batch.push(decrypted);
+            }
+            this.items.push(...stored);
+            this.lastCheckpoint = maxTs;
+            this.logger?.pullSuccess(this.loggerName, Math.round(performance.now() - start), skipped > 0 ? { skippedCount: skipped } : undefined);
+            return batch;
+        }
+        catch (err) {
+            this.logger?.pullError(this.loggerName, err instanceof Error ? err.message : String(err));
+            throw err;
+        }
+    }
+    /** Verify a single element's author signature over its RAW (pre-decryption)
+     *  `data`. Throws {@link AppendAuthorError} on any failure. No-op when
+     *  verification is disabled. */
+    verifyOne(el) {
+        if (!this.verifyAuthor)
+            return;
+        const policy = typeof this.verifyAuthor === "object" ? this.verifyAuthor : {};
+        const { authorPubkey, authorSignature } = el;
+        if (!authorPubkey || !authorSignature)
+            throw new AppendAuthorError(el.ts);
+        // Public keys are hex, which is case-insensitive — compare normalized so a
+        // caller passing a differently-cased `expectedAuthorPubkey` isn't falsely rejected.
+        if (policy.expectedAuthorPubkey &&
+            authorPubkey.toLowerCase() !== policy.expectedAuthorPubkey.toLowerCase()) {
+            throw new AppendAuthorError(el.ts);
+        }
+        void policy;
+        const ok = verifyAppendAuthor(this.documentKey, el.data, authorPubkey, authorSignature);
+        if (!ok)
+            throw new AppendAuthorError(el.ts);
+    }
+    /** The full accumulated log (a shallow copy), in `ts` order. Under
+     *  `persistEncrypted` these carry CIPHERTEXT `data` (persist them as-is, then
+     *  re-seed via `initialItems`); otherwise they carry decrypted/plaintext data. */
+    getItems() {
+        return [...this.items];
+    }
+    /**
+     * The full accumulated log, DECRYPTED — for rendering warm-started history in
+     * `persistEncrypted` mode (where {@link getItems} holds ciphertext). Honors
+     * `onElementError` (a `"skip"` cursor drops elements it cannot read). When the
+     * cursor has no `encryptor`, or is not in `persistEncrypted` mode, the held
+     * elements are already plaintext/decrypted and are returned as-is.
+     */
+    async getDecryptedItems() {
+        const snapshot = [...this.items];
+        if (!this.encryptor || !this.persistEncrypted)
+            return snapshot;
+        const out = [];
+        for (const el of snapshot) {
+            try {
+                this.verifyOne(el);
+                const data = await this.encryptor.decrypt(el.data);
+                out.push(withAuthor(el.ts, data, el));
+            }
+            catch (err) {
+                if (this.onElementError !== "skip")
+                    throw err;
+            }
+        }
+        return out;
+    }
+    /** The current checkpoint: the max `ts` held (the next pull's `since`). `0`
+     *  when nothing has been pulled or seeded. */
+    getCheckpoint() {
+        return this.lastCheckpoint;
+    }
+    /** Restore the checkpoint without seeding items — for persistence layers that
+     *  store only the checkpoint. Used to resume incrementally across restarts.
+     *  Rejects a value below the max `ts` already held: rewinding would make the
+     *  next pull re-deliver, and duplicate, elements the cursor already has. */
+    setCheckpoint(ts) {
+        if (ts < checkpointOf(this.items)) {
+            throw new Error("checkpoint must be >= the max ts already held");
+        }
+        this.lastCheckpoint = ts;
+    }
+}

package/dist/cap-mint.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Phase-2 transitional shim. `mintDeviceCap` + `scopes.rootAll` now live in
+ * `@drakkar.software/starfish-identities`; `mintMemberCap` +
+ * `scopes.readOnly`/`scopes.writer`/`scopes.admin` now live in
+ * `@drakkar.software/starfish-sharing`. The `scopes` re-export here merges
+ * both so existing imports of `import { scopes } from
+ * "../src/cap-mint.js"` keep working. Removed in Phase 3.
+ */
+import { type ScopePreset as IdentityScopePreset, type MintOpts as IdentityMintOpts } from "@drakkar.software/starfish-identities";
+export { mintDeviceCap } from "@drakkar.software/starfish-identities";
+export { mintMemberCap } from "@drakkar.software/starfish-sharing";
+/** @deprecated Phase-2 transitional facade. Use the per-package `scopes` directly. */
+export declare const scopes: {
+    readOnly: (c: string) => import("@drakkar.software/starfish-sharing").ScopePreset;
+    writer: (c: string) => import("@drakkar.software/starfish-sharing").ScopePreset;
+    admin: (c: string) => import("@drakkar.software/starfish-sharing").ScopePreset;
+    rootAll: () => IdentityScopePreset;
+};
+export type ScopePreset = IdentityScopePreset;
+export type MintOpts = IdentityMintOpts;

package/dist/cap-mint.js

@@ -0,0 +1,12 @@
+// src/cap-mint.ts
+import { scopes as identityScopes } from "@drakkar.software/starfish-identities";
+import { scopes as sharingScopes } from "@drakkar.software/starfish-sharing";
+import { mintDeviceCap } from "@drakkar.software/starfish-identities";
+import { mintMemberCap } from "@drakkar.software/starfish-sharing";
+var scopes = { ...identityScopes, ...sharingScopes };
+export {
+  mintDeviceCap,
+  mintMemberCap,
+  scopes
+};
+//# sourceMappingURL=cap-mint.js.map

package/dist/cap-mint.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/cap-mint.ts"],
+  "sourcesContent": ["/**\n * Phase-2 transitional shim. `mintDeviceCap` + `scopes.rootAll` now live in\n * `@drakkar.software/starfish-identities`; `mintMemberCap` +\n * `scopes.readOnly`/`scopes.writer`/`scopes.admin` now live in\n * `@drakkar.software/starfish-sharing`. The `scopes` re-export here merges\n * both so existing imports of `import { scopes } from\n * \"../src/cap-mint.js\"` keep working. Removed in Phase 3.\n */\nimport { scopes as identityScopes, type ScopePreset as IdentityScopePreset, type MintOpts as IdentityMintOpts } from \"@drakkar.software/starfish-identities\"\nimport { scopes as sharingScopes } from \"@drakkar.software/starfish-sharing\"\n\nexport { mintDeviceCap } from \"@drakkar.software/starfish-identities\"\nexport { mintMemberCap } from \"@drakkar.software/starfish-sharing\"\n\n/** @deprecated Phase-2 transitional facade. Use the per-package `scopes` directly. */\nexport const scopes = { ...identityScopes, ...sharingScopes }\n\nexport type ScopePreset = IdentityScopePreset\nexport type MintOpts = IdentityMintOpts\n"],
+  "mappings": ";AAQA,SAAS,UAAU,sBAAkG;AACrH,SAAS,UAAU,qBAAqB;AAExC,SAAS,qBAAqB;AAC9B,SAAS,qBAAqB;AAGvB,IAAM,SAAS,EAAE,GAAG,gBAAgB,GAAG,cAAc;",
+  "names": []
+}