@muhkoo/connect 0.9.0-alpha.0 → 0.10.1-alpha.0

package/dist/browser/index.js

@@ -3796,6 +3796,8 @@ class ReedSolomonCodec {
  *                             skip a PUT they'd otherwise dedup-rewrite. The
  *                             server can ignore the optimization if it wants.
  */
+/** Peer head-start (ms) before origin joins the race in {@link ShardClient.getShard}. */
+const HEDGE_MS = 500;
 /**
  * Compute the lowercase hex SHA-256 of `bytes`. Available via WebCrypto in
  * every runtime this SDK targets.
@@ -3897,31 +3899,63 @@ class ShardClient {
             if (cached)
                 return cached;
         }
-        // Peers next: ask the Space swarm before spending origin egress. Peer
-        // blocks are hash-verified by the block engine; on miss/timeout we fall
-        // through to origin. Best-effort — never let a peer error block a read.
-        if (this.peers) {
-            try {
-                const fromPeer = await this.peers.getBlock(hash);
-                if (fromPeer) {
+        // No peers → straight to origin.
+        if (!this.peers)
+            return this.fetchFromOrigin(hash);
+        // HEDGED RACE: prefer a peer (saves origin egress) but never let a slow
+        // or missing peer stall delivery — give the peer a short head start, then
+        // start origin in parallel and take whichever returns the block first.
+        const peers = this.peers;
+        return new Promise((resolve, reject) => {
+            let done = false;
+            let originStarted = false;
+            let timer = null;
+            const win = (b) => {
+                if (done)
+                    return;
+                done = true;
+                if (timer)
+                    clearTimeout(timer);
+                resolve(b);
+            };
+            const fail = (e) => {
+                if (!done) {
+                    done = true;
+                    reject(e);
+                }
+            };
+            const startOrigin = () => {
+                if (originStarted || done)
+                    return;
+                originStarted = true;
+                if (timer) {
+                    clearTimeout(timer);
+                    timer = null;
+                }
+                this.fetchFromOrigin(hash).then(win, fail);
+            };
+            timer = setTimeout(startOrigin, HEDGE_MS);
+            peers.getBlock(hash).then((b) => {
+                if (b) {
                     if (this.cache)
-                        void this.cache.put(hash, fromPeer);
-                    return fromPeer;
+                        void this.cache.put(hash, b);
+                    win(b); // peer delivered first
                 }
-            }
-            catch {
-                /* peer layer hiccup — fall through to origin */
-            }
-        }
+                else {
+                    startOrigin(); // peer miss → don't wait out the hedge
+                }
+            }, () => startOrigin());
+        });
+    }
+    /** Fetch a shard from origin. Returns `null` for 404 (or offline when a
+     *  cache is present, so RS recovery can proceed); throws otherwise. */
+    async fetchFromOrigin(hash) {
         const url = this.urlForHash(hash);
         let response;
         try {
             response = await this.fetchFn(url, { method: "GET" });
         }
         catch (err) {
-            // Offline with no cache hit: report the shard as missing so
-            // FileStorage's Reed–Solomon recovery can still reconstruct from the
-            // shards that ARE cached. Rethrow when there's no cache to fall back on.
             if (this.cache)
                 return null;
             throw err;
@@ -3932,8 +3966,7 @@ class ShardClient {
             const text = await safeText(response);
             throw new Error(`ShardClient.getShard(${hash}) failed (${response.status}): ${text}`);
         }
-        const buf = await response.arrayBuffer();
-        const bytes = new Uint8Array(buf);
+        const bytes = new Uint8Array(await response.arrayBuffer());
         if (this.cache)
             void this.cache.put(hash, bytes);
         return bytes;
@@ -4961,7 +4994,7 @@ function base64UrlDecode(s) {
  * expect (and isn't serving a stale cached bundle). Keep this in sync with
  * `package.json` `version`.
  */
-const VERSION = "0.9.0-alpha.0";
+const VERSION = "0.10.1-alpha.0";
 
 /**
  * `HttpClient` — the one place the unified {@link Client} talks to the
@@ -4984,6 +5017,28 @@ const VERSION = "0.9.0-alpha.0";
  * convenience JSON helpers (`get`/`post`/`del`) for code that talks to the
  * accelerator directly.
  */
+/** Per-request timing logs, enabled on staging only (temporary diagnostic). */
+const HTTP_DEBUG = (() => {
+    try {
+        return typeof location !== "undefined" && /(^|\.)staging\./.test(location.hostname);
+    }
+    catch {
+        return false;
+    }
+})();
+/** Short, readable request path (pathname + search) for the timing log. */
+function reqPath(input) {
+    try {
+        const u = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+        if (!/^https?:\/\//i.test(u))
+            return u;
+        const parsed = new URL(u);
+        return parsed.pathname + parsed.search;
+    }
+    catch {
+        return "?";
+    }
+}
 /** Thrown for any non-2xx accelerator response. Carries the HTTP status. */
 class HttpError extends Error {
     status;
@@ -5040,7 +5095,14 @@ class HttpClient {
             if (token)
                 headers.set("X-Muhkoo-Session", token);
         }
-        return this.fetchFn(input, { ...init, headers });
+        const finalInit = { ...init, headers };
+        if (!HTTP_DEBUG)
+            return this.fetchFn(input, finalInit);
+        // Staging diagnostic: time every accelerator request (this `fetch` is the
+        // single chokepoint — JSON helpers + the roster/shard fetches ride it).
+        const t = performance.now();
+        const tag = `${init?.method ?? "GET"} ${reqPath(input)}`;
+        return this.fetchFn(input, finalInit).then((res) => { console.info(`[muhkoo:http] ${tag} → ${res.status} ${Math.round(performance.now() - t)}ms`); return res; }, (err) => { console.info(`[muhkoo:http] ${tag} → ERROR ${Math.round(performance.now() - t)}ms`); throw err; });
     };
     /** True when `input` resolves to {@link baseOrigin} (relative URLs always do). */
     isSameOrigin(input) {
@@ -5854,6 +5916,34 @@ class ZkAuth {
             return null;
         }
     }
+    /**
+     * Boot helper — call this once on app start. Restores the session AND, when a
+     * passkey is enrolled, silently unlocks the identity via WebAuthn (recovering
+     * the master seed so the ratchet keypair rehydrates and `client.kv` works).
+     * The seed is never persisted, so a passkey (or password) is the only way to
+     * unlock after a reload — this keeps that off the app's plate.
+     *
+     * Returns `{ user, unlocked }`. When `unlocked` is false (no passkey, the
+     * user cancelled, or the browser required a gesture), prompt for a password
+     * and call {@link unlock}. Apps need no key-management scaffolding beyond this.
+     */
+    async resume() {
+        const user = await this.restore();
+        if (!user)
+            return { user: null, unlocked: false };
+        if (this.deps.session.isUnlocked)
+            return { user, unlocked: true };
+        try {
+            const factors = await this.listFactors();
+            if (factors.some((f) => f.type === "passkey")) {
+                await this.loginWithPasskey(user.username);
+            }
+        }
+        catch {
+            /* no passkey / cancelled / no user gesture — leave locked for a prompt */
+        }
+        return { user, unlocked: this.deps.session.isUnlocked };
+    }
     /**
      * Re-derive identity material for an already-authenticated (restored)
      * session, so the client can decrypt storage and run the ratchet. Verifies
@@ -7205,18 +7295,23 @@ class Space {
         const hlc = await offline.nextHlc();
         const packet = await this.sealMessage(payload, opts.channel, opts.contentType, clientId);
         const frame = { spaceMessage: packet };
-        await offline.putMessage(this.id, {
+        const entry = {
             handle: provisionalSpaceKey(clientId),
             packet,
             op: "msg",
             clientId,
             hlc,
             pending: true,
-        });
-        if (this.isConnected())
-            this.sendRaw(frame);
-        else
+        };
+        if (this.isConnected()) {
+            this.sendRaw(frame); // send first — don't block the wire on IndexedDB
+            void offline.putMessage(this.id, entry); // optimistic cache off the hot path
+        }
+        else {
+            // Offline: persist the optimistic entry + durable replay queue.
+            void offline.putMessage(this.id, entry);
             await offline.enqueueFrame(this.id, frame, clientId, hlc);
+        }
     }
     /** Subscribe to decrypted fan-out messages. Returns an unsubscribe fn. */
     onMessage(handler) {
@@ -7280,18 +7375,14 @@ class Space {
         const offline = this.deps.offline;
         if (!offline?.enabled || !this.cipher)
             return [];
-        const entries = await offline.loadMessages(this.id);
+        const entries = (await offline.loadMessages(this.id)).filter((e) => !e.deleted && e.packet);
+        // Decode in parallel (already verified when cached → skipVerify).
+        const decodedAll = await Promise.all(entries.map((e) => this.decodeFrame(e.packet, this.cipher, /*isRawFrame*/ true, e.pending ? 0 : Number(e.handle), /*skipVerify*/ true)));
         const out = [];
-        for (const e of entries) {
-            if (e.deleted || !e.packet)
-                continue;
-            // Already verified when first cached → skip re-verification (which
-            // would also fail offline without a warm member directory).
-            const decoded = await this.decodeFrame(e.packet, this.cipher, 
-            /*isRawFrame*/ true, e.pending ? 0 : Number(e.handle), 
-            /*skipVerify*/ true);
+        for (let i = 0; i < decodedAll.length; i++) {
+            const decoded = decodedAll[i];
             if (decoded) {
-                decoded.pending = e.pending;
+                decoded.pending = entries[i].pending;
                 out.push(decoded);
             }
         }
@@ -7348,25 +7439,45 @@ class Space {
             params.set("limit", String(opts.limit));
         const url = `${this.deps.httpBaseUrl}/api/spaces/${encodeURIComponent(this.name)}/history` +
             (params.toString() ? `?${params}` : "");
+        // Temporary staging diagnostic: split fetch / directory / decode time.
+        const dbg = (() => { try {
+            return globalThis.location?.hostname?.includes("staging");
+        }
+        catch {
+            return false;
+        } })();
+        const mark = () => (typeof performance !== "undefined" ? performance.now() : Date.now());
+        const t0 = mark();
         const res = await this.deps.fetch(url);
         if (!res.ok)
             throw new Error(`Space.history: ${res.status} ${res.statusText}`);
         const body = (await res.json());
+        const tFetch = mark();
         // Warm the member directory once so historical senders' signatures verify.
-        // (refreshDirectory swallows its own transport errors.)
-        await this.deps.keyring?.refreshDirectory();
+        // Force past the cooldown — a history load is an explicit "get fresh".
+        await this.deps.keyring?.refreshDirectory({ force: true });
+        const tDir = mark();
+        // Decode the whole page in PARALLEL — each frame is an AES-GCM decrypt +
+        // ECDSA verify on the WebCrypto thread; doing them sequentially (await
+        // per message) serializes ~100 main↔crypto round-trips and dominates
+        // load time. Promise.all preserves input order.
+        const raws = body.messages ?? [];
+        const decodedAll = await Promise.all(raws.map((raw) => this.decodeFrame(raw, cipher)));
+        if (dbg) {
+            console.info(`[muhkoo:space] history n=${raws.length} | fetch ${Math.round(tFetch - t0)}ms | dir ${Math.round(tDir - tFetch)}ms | decode ${Math.round(mark() - tDir)}ms`);
+        }
         const messages = [];
-        for (const raw of body.messages ?? []) {
-            const decoded = await this.decodeFrame(raw, cipher);
+        for (let i = 0; i < decodedAll.length; i++) {
+            const decoded = decodedAll[i];
             if (!decoded)
                 continue;
             messages.push(decoded);
-            // Warm the offline cache with the inner sealed packet at its handle.
+            // Warm the offline cache off the hot path (best-effort, non-blocking).
             if (this.deps.offline?.enabled) {
                 try {
-                    const outer = JSON.parse(raw);
+                    const outer = JSON.parse(raws[i]);
                     if (typeof outer.spaceMessage === "string") {
-                        await this.cacheFrame(outer.spaceMessage, decoded, "msg");
+                        void this.cacheFrame(outer.spaceMessage, decoded, "msg");
                     }
                 }
                 catch {
@@ -7463,8 +7574,8 @@ class Space {
             const handle = Number(f.timestamp ?? 0);
             const decoded = await this.decodeFrame(f.spaceMessage, this.cipher, /*raw*/ true, handle);
             if (decoded) {
-                this.emitEvent("message", decoded);
-                await this.cacheFrame(f.spaceMessage, decoded, "msg");
+                this.emitEvent("message", decoded); // UI first
+                void this.cacheFrame(f.spaceMessage, decoded, "msg"); // cache off the hot path
             }
             return;
         }
@@ -7476,7 +7587,7 @@ class Space {
                 const decoded = await this.decodeFrame(e.spaceMessage, this.cipher, /*raw*/ true, Number(e.ts ?? 0));
                 if (decoded) {
                     this.emitEvent("message-edited", decoded);
-                    await this.cacheFrame(e.spaceMessage, decoded, "edit");
+                    void this.cacheFrame(e.spaceMessage, decoded, "edit");
                 }
             }
             return;
@@ -7486,8 +7597,8 @@ class Space {
             const handle = Number(d.ts ?? 0);
             this.emitEvent("message-deleted", { handle });
             if (this.deps.offline?.enabled) {
-                await this.deps.offline.putDeleted(this.id, handle);
-                await this.deps.offline.observeHandle(this.id, handle);
+                // Cache the tombstone off the hot path.
+                void this.deps.offline.putDeleted(this.id, handle).then(() => this.deps.offline?.observeHandle(this.id, handle));
             }
             return;
         }
@@ -7508,7 +7619,7 @@ class Space {
             this.emitEvent("join-request", req);
             // A new member appeared — refresh the directory so their future
             // messages verify, and (if we hold the key) auto-admit them.
-            void this.deps.keyring?.refreshDirectory();
+            void this.deps.keyring?.refreshDirectory({ force: true });
             if (this.deps.autoAdmit !== false && this.deps.keyring?.hasAnyKey() && req.memberId !== this.deps.myId()) {
                 void this.deps.keyring.admit(req.memberId, req.identityEcdhPub).catch(() => { });
             }
@@ -7658,7 +7769,7 @@ class Space {
         const cursor = await offline.getCursor(this.id);
         let since = String(cursor?.lastSeenHandle ?? 0);
         // Warm the member directory once so historical senders' signatures verify.
-        await this.deps.keyring?.refreshDirectory();
+        await this.deps.keyring?.refreshDirectory({ force: true });
         for (let page = 0; page < 50; page++) {
             const url = `${this.deps.httpBaseUrl}/api/spaces/${encodeURIComponent(this.name)}/history` +
                 `?since=${encodeURIComponent(since)}&limit=100`;
@@ -7921,6 +8032,19 @@ function parseMaybeJson(text) {
  * `KEEPER_MEMBER_ID`.
  */
 const KEEPER_MEMBER_ID = "__keeper__";
+/** Staging-only keyring diagnostics (group-key cache hit/miss, persist, pulls). */
+const KEYRING_DEBUG = (() => {
+    try {
+        return typeof location !== "undefined" && /(^|\.)staging\./.test(location.hostname);
+    }
+    catch {
+        return false;
+    }
+})();
+function klog(msg) {
+    if (KEYRING_DEBUG)
+        console.info(`[muhkoo:keyring] ${msg}`);
+}
 class SpaceKeyring {
     deps;
     keys = new Map();
@@ -7928,6 +8052,14 @@ class SpaceKeyring {
     policy;
     /** Cached member directory: memberId → imported ECDSA verify key. */
     memberEcdsa = new Map();
+    /** Coalesce concurrent roster refreshes (the parallel history/backlog decode
+     *  would otherwise fire one `roster` fetch PER message — a thundering herd). */
+    dirInFlight = null;
+    dirRefreshedAt = 0;
+    /** Min gap between non-forced roster refreshes. A miss that persists within
+     *  this window won't re-fetch (the roster hasn't changed that fast); genuine
+     *  membership changes use `{ force: true }` (join requests / history loads). */
+    static DIR_COOLDOWN_MS = 5000;
     constructor(deps) {
         this.deps = deps;
         this.policy = deps.historyPolicy ?? "static";
@@ -7937,8 +8069,27 @@ class SpaceKeyring {
     ecdsaKeyFor(memberId) {
         return this.memberEcdsa.get(memberId);
     }
-    /** Refresh the member directory (memberId → ECDSA key) from the roster. */
-    async refreshDirectory() {
+    /**
+     * Refresh the member directory (memberId → ECDSA key) from the roster.
+     * Coalesces concurrent callers into ONE fetch, and skips a fetch when one
+     * completed within {@link DIR_COOLDOWN_MS} (unless `force`). Without this, a
+     * page of N messages decoded in parallel — each missing the cold directory —
+     * fires N simultaneous `roster` requests that queue behind the browser's
+     * connection limit and take many seconds.
+     */
+    async refreshDirectory(opts) {
+        if (this.dirInFlight)
+            return this.dirInFlight; // a refresh is already running
+        if (!opts?.force && Date.now() - this.dirRefreshedAt < SpaceKeyring.DIR_COOLDOWN_MS) {
+            return; // refreshed very recently — the roster won't have changed
+        }
+        this.dirInFlight = this.doRefreshDirectory().finally(() => {
+            this.dirRefreshedAt = Date.now();
+            this.dirInFlight = null;
+        });
+        return this.dirInFlight;
+    }
+    async doRefreshDirectory() {
         let roster;
         try {
             roster = await this.deps.transport.fetchRoster();
@@ -7973,34 +8124,63 @@ class SpaceKeyring {
     async loadFromCache() {
         if (!this.deps.cache)
             return false;
+        // The cache entries are ECIES-wrapped to our identity key, so we unwrap
+        // with the keyring's OWN private key — available whenever chat works,
+        // unlike client.kv's StorageCipher which needs the full unlocked identity.
+        const priv = this.deps.ownPrivateKey();
+        if (!priv) {
+            klog("loadFromCache: no private key available yet");
+            return false;
+        }
         let cached;
         try {
             cached = await this.deps.cache.loadKeys(this.deps.spaceId);
         }
-        catch {
+        catch (e) {
+            klog(`loadFromCache: ERROR reading cache — ${e instanceof Error ? e.message : e}`);
             return false;
         }
-        if (!cached)
+        if (!cached) {
+            klog("loadFromCache: cache empty");
+            return false;
+        }
+        for (const [epochStr, serialized] of Object.entries(cached)) {
+            try {
+                const blob = JSON.parse(serialized);
+                this.keys.set(Number(epochStr), await unwrapSpaceKey(blob, priv));
+            }
+            catch {
+                /* stale / old-format entry — skip; we'll re-admit and re-persist */
+            }
+        }
+        if (this.keys.size === 0) {
+            klog("loadFromCache: no usable entries (stale format → will re-admit)");
             return false;
-        for (const [epochStr, b64] of Object.entries(cached)) {
-            this.keys.set(Number(epochStr), fromBase64$1(b64));
         }
         this.epoch = Math.max(0, ...Array.from(this.keys.keys()));
-        return this.keys.size > 0;
+        klog(`loadFromCache: HIT ${this.keys.size} epoch(s), current=${this.epoch}`);
+        return true;
     }
     async persist() {
-        if (!this.deps.cache)
+        if (!this.deps.cache || this.keys.size === 0)
             return;
-        const out = {};
-        for (const [epoch, key] of this.keys)
-            out[String(epoch)] = toBase64$1(key);
-        // Best-effort: caching is an optimization; a write failure (e.g. locked
-        // storage) must not break key acquisition.
+        // Best-effort: caching is an optimization; a write failure must not break
+        // key acquisition.
         try {
+            // Wrap each epoch key to our OWN identity key (ECIES-to-self). The
+            // cache stays server-blind (the kv layer stores it with encrypt:false
+            // — it's already encrypted) AND readable with the keyring private key
+            // alone, so it works while the full identity is locked (post-reload).
+            const selfPub = await importEcdhPublicKey(this.deps.identityEcdhPub);
+            const out = {};
+            for (const [epoch, key] of this.keys) {
+                out[String(epoch)] = JSON.stringify(await wrapSpaceKey(key, epoch, selfPub));
+            }
             await this.deps.cache.saveKeys(this.deps.spaceId, out);
+            klog(`persist: saved ${Object.keys(out).length} epoch(s)`);
         }
-        catch {
-            /* ignore */
+        catch (e) {
+            klog(`persist: FAILED — ${e instanceof Error ? e.message : e}`);
         }
     }
     /** Creator path: mint epoch-0 group key for a brand-new space. */
@@ -8049,8 +8229,24 @@ class SpaceKeyring {
             this.epoch = Math.max(this.epoch, ...Array.from(this.keys.keys()));
             await this.persist();
         }
+        klog(`pullKeys: +${added} epoch(s) (now hold ${this.keys.size}, current=${this.epoch})`);
         return added;
     }
+    /**
+     * Background freshness check for the cache-hit fast path: confirm we hold the
+     * current epoch (picks up a rotation / our removal) WITHOUT the full newcomer
+     * admit handshake. Cheap + idempotent; never blocks first paint. Returns the
+     * number of newly-obtained epoch keys (0 = already current).
+     */
+    async reconcile() {
+        await this.refreshDirectory({ force: true });
+        try {
+            return await this.pullKeys();
+        }
+        catch {
+            return 0; // best-effort — the live keyringReady frame is the backstop
+        }
+    }
     // -- key-holder: admit + rotate -------------------------------------------
     /**
      * Wrap our group key(s) for a newcomer and post the blobs. In a `static`
@@ -8450,14 +8646,22 @@ class ShardCache {
 class PeerExchange {
     engine;
     timeoutMs;
+    debug;
     constructor(engine, opts = {}) {
         this.engine = engine;
         this.timeoutMs = opts.timeoutMs ?? 2500;
+        this.debug = opts.debug ?? false;
     }
-    getBlock(hash, opts) {
-        return this.engine.want(hash, opts?.timeoutMs ?? this.timeoutMs);
+    async getBlock(hash, opts) {
+        const bytes = await this.engine.want(hash, opts?.timeoutMs ?? this.timeoutMs);
+        if (this.debug) {
+            console.info(`%c[muhkoo:p2p] ${bytes ? "✓ peer-served" : "✗ miss → origin"} shard ${hash.slice(0, 10)}…`, `color:${bytes ? "#58da7d" : "#888"}`);
+        }
+        return bytes;
     }
     announce(hash) {
+        if (this.debug)
+            console.info(`[muhkoo:p2p] announce shard ${hash.slice(0, 10)}…`);
         this.engine.announce(hash);
     }
 }
@@ -9145,7 +9349,11 @@ class PeerNetwork {
                 this.signaler.send(from, "hello", { broadcast: false });
             }
         }));
-        this.exchange = new PeerExchange(this.host, { timeoutMs: opts.timeoutMs });
+        this.exchange = new PeerExchange(this.host, { timeoutMs: opts.timeoutMs, debug: opts.debug });
+        if (opts.debug) {
+            console.info("[muhkoo:p2p] mesh attached for space; awaiting peers…");
+            this.offs.push(this.transport.onPeerChange((peers) => console.info(`%c[muhkoo:p2p] connected peers: ${peers.length}`, "color:#58da7d", peers)));
+        }
     }
     /**
      * Begin peer discovery — broadcast a hello so existing members dial us and
@@ -9443,6 +9651,7 @@ class SpaceNamespace {
                 workerFactory: this.deps.p2p.workerFactory,
                 iceServers: this.deps.p2p.iceServers,
                 maxPeers: this.deps.p2p.maxPeers,
+                debug: this.deps.p2p.debug,
             }));
         }
         return space;
@@ -9451,7 +9660,34 @@ class SpaceNamespace {
     async ensureIdentity(memberId) {
         const store = KeyStore.getInstance();
         if (!store.getKeyPair(memberId)) {
-            await store.generateOwnKeyPair(memberId);
+            // Unlocked (seed in hand): rehydrate the member's STABLE keypair from
+            // the vault, or provision + persist one on first use. This keeps the
+            // member the same identity across reloads — no re-admit each session,
+            // and the group-key cache round-trips. Best-effort: a personal-space
+            // hiccup falls through to an ephemeral keypair (today's behavior).
+            const seed = this.deps.session.seed;
+            const staging = (() => { try {
+                return typeof location !== "undefined" && /(^|\.)staging\./.test(location.hostname);
+            }
+            catch {
+                return false;
+            } })();
+            if (staging)
+                console.info(`[muhkoo:vault] ensureIdentity: unlocked=${!!seed} vault=${!!this.deps.chatKeys}`);
+            if (this.deps.chatKeys && seed) {
+                try {
+                    await this.deps.chatKeys.ensure(memberId, toBase64$1(seed));
+                }
+                catch (e) {
+                    if (staging)
+                        console.info(`[muhkoo:vault] ensureIdentity: vault.ensure failed — ${e instanceof Error ? e.message : e}`);
+                }
+            }
+            if (!store.getKeyPair(memberId)) {
+                if (staging)
+                    console.info("[muhkoo:vault] ensureIdentity: EPHEMERAL keypair (locked / no vault) → will re-admit");
+                await store.generateOwnKeyPair(memberId);
+            }
         }
         const ecdhPub = await exportEcdhPublicKey(store.getKeyPair(memberId).publicKey);
         const ecdsaPub = await exportEcdsaPublicKey(store.getAuthKeyPair(memberId).publicKey);
@@ -9692,6 +9928,112 @@ class FunctionsNamespace {
     }
 }
 
+/**
+ * `ChatKeyVault` — SDK-owned lifecycle for a member's long-lived ratchet/space
+ * keypair (the connect `KeyStore` entry keyed by the member id / username).
+ *
+ * Historically each app hand-rolled this (see the web app's old
+ * `personal/spaceLoader.ts`): generate a keypair at register, seed-wrap it, and
+ * PUT it to the personal space; on login GET + unwrap + hydrate the `KeyStore`.
+ * That scaffolding now lives here so ANY app gets a **stable** member keypair
+ * across reloads for free — without which the member re-admits to every space on
+ * every load and the group-key cache can never round-trip.
+ *
+ * Security invariant: the wrapping secret is the **master seed** (not the
+ * password), so the blob survives password changes and unlocks under a passkey.
+ * The seed is only ever held in memory (never persisted), so this vault can only
+ * provision/rehydrate while the client is unlocked.
+ */
+/** Staging-only diagnostics: is the member keypair stable across reloads? */
+const VAULT_DEBUG = (() => {
+    try {
+        return typeof location !== "undefined" && /(^|\.)staging\./.test(location.hostname);
+    }
+    catch {
+        return false;
+    }
+})();
+function vlog(msg) {
+    if (VAULT_DEBUG)
+        console.info(`[muhkoo:vault] ${msg}`);
+}
+/** A short, stable fingerprint of the member's current keypair (ecdsa pub). */
+async function fingerprint(memberId) {
+    try {
+        const raw = await KeyStore.getInstance().getRawEcdsaPublicKey(memberId);
+        if (!raw)
+            return "none";
+        let s = 0;
+        for (const b of raw)
+            s = (s * 31 + b) >>> 0;
+        return s.toString(16).padStart(8, "0");
+    }
+    catch {
+        return "err";
+    }
+}
+/** Personal-space key holding the seed-wrapped, dehydrated ratchet keypair. */
+const CHAT_KEYS_KEY = "chat-keys";
+class ChatKeyVault {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    /**
+     * Register-time: ensure a keypair exists for `memberId`, seed-wrap the
+     * dehydrated form, and persist it to the personal space. Idempotent — reuses
+     * an existing in-tab keypair rather than minting a second one.
+     */
+    async provision(memberId, seedSecret) {
+        const ks = KeyStore.getInstance();
+        if (!ks.getKeyPair(memberId)) {
+            try {
+                await ks.generateOwnKeyPair(memberId);
+            }
+            catch (e) {
+                if (!String(e?.message ?? e).includes("already exists"))
+                    throw e;
+            }
+        }
+        const dehydrated = await ks.dehydrateKeyPair(memberId);
+        const plaintext = new TextEncoder().encode(JSON.stringify(dehydrated));
+        await this.store.put(CHAT_KEYS_KEY, await wrapWithPassphrase(seedSecret, plaintext));
+        vlog(`provision: minted+persisted keypair fp=${await fingerprint(memberId)}`);
+    }
+    /**
+     * Sign-in / unlock time: fetch the wrapped blob, unwrap with the seed, and
+     * hydrate the `KeyStore` — restoring the SAME keypair the member had before.
+     * Returns `true` when a keypair is now in hand (already present or hydrated),
+     * `false` when there's no blob yet (a brand-new member → caller provisions).
+     * Throws only on a genuine unwrap failure (wrong secret / tampered blob).
+     */
+    async rehydrate(memberId, seedSecret) {
+        // Already unlocked in this tab — nothing to do.
+        if (KeyStore.getInstance().getKeyPair(memberId)?.privateKey)
+            return true;
+        const wrapped = await this.store.get(CHAT_KEYS_KEY);
+        if (!wrapped) {
+            vlog("rehydrate: no chat-keys blob (new member → will provision)");
+            return false;
+        }
+        const bytes = await unwrapWithPassphrase(seedSecret, wrapped);
+        const dehydrated = JSON.parse(new TextDecoder().decode(bytes));
+        await KeyStore.getInstance().hydrateKeyPair(memberId, dehydrated);
+        vlog(`rehydrate: HIT — restored stable keypair fp=${await fingerprint(memberId)}`);
+        return true;
+    }
+    /**
+     * Ensure a stable keypair is in hand: rehydrate from the vault if a blob
+     * exists, otherwise mint one and persist it (so it's stable next session).
+     * Used at register and lazily when a space is first opened.
+     */
+    async ensure(memberId, seedSecret) {
+        if (await this.rehydrate(memberId, seedSecret))
+            return;
+        await this.provision(memberId, seedSecret);
+    }
+}
+
 /**
  * `HlcTimestamp` — a Hybrid Logical Clock reading, packed into a single
  * lexicographically-sortable string so the whole offline layer (and the
@@ -10919,11 +11261,38 @@ class Client {
         this.message = new MessageNamespace({ http: this.http, session: this.session, wsBaseUrl });
         // Group keys are cached in the user's PersonalSpace (encrypted at rest
         // by client.kv), so a returning member hydrates without a fresh keyring
-        // round-trip. The server only ever sees the ciphertext.
+        // round-trip. The server only ever sees ciphertext.
+        //
+        // `encrypt: false` is deliberate: the keyring already ECIES-wraps each
+        // key to the member's identity (server-blind), and StorageCipher would
+        // additionally require the FULL unlocked identity (`requireIdentity()`),
+        // which is locked after a page reload — that coupling is exactly why the
+        // cache previously never read or persisted. The wrapped blobs are opaque.
         const spaceKeyCache = {
             loadKeys: (spaceId) => this.kv.get("space-keys", spaceId),
-            saveKeys: (spaceId, keys) => this.kv.set("space-keys", spaceId, keys),
+            saveKeys: (spaceId, keys) => this.kv.set("space-keys", spaceId, keys, { encrypt: false }),
+        };
+        // SDK-owned vault for the member's long-lived ratchet/space keypair.
+        // Stored at the personal-space `chat-keys` key (same key the app used to
+        // manage by hand), seed-wrapped, session-token authed (no snarkjs). This
+        // gives every app a STABLE keypair across reloads — no per-app scaffolding
+        // — so members don't re-admit each load and the group-key cache works.
+        const chatKeyStore = {
+            get: async (key) => {
+                const c = this.session.commitment;
+                if (!c)
+                    return null;
+                const res = await this.http.post(`/api/personal/${encodeURIComponent(c)}/kv/${encodeURIComponent(key)}/get`, {});
+                return (res?.value ?? null);
+            },
+            put: async (key, value) => {
+                const c = this.session.commitment;
+                if (!c)
+                    throw new Error("ChatKeyVault: no session — sign in first.");
+                await this.http.post(`/api/personal/${encodeURIComponent(c)}/kv/${encodeURIComponent(key)}`, { value });
+            },
         };
+        const chatKeys = new ChatKeyVault(chatKeyStore);
         this.space = new SpaceNamespace({
             http: this.http,
             session: this.session,
@@ -10931,6 +11300,7 @@ class Client {
             cache: spaceKeyCache,
             offline: this.offline,
             p2p: options.p2p,
+            chatKeys,
         });
         this.agents = new AgentsNamespace({ http: this.http });
         this.functions = new FunctionsNamespace({ http: this.http, fnHostSuffix: options.functionsHostSuffix });