@muhkoo/connect 0.2.0-alpha.2 → 0.4.0-alpha.1

package/dist/server/index.js

@@ -2562,7 +2562,7 @@ async function poseidonHash(inputs) {
  * worker depending on `VITE_WORKER_URL`.
  */
 let _snarkjs$1 = null;
-async function loadSnarkjs$2() {
+async function loadSnarkjs$1() {
     if (_snarkjs$1)
         return _snarkjs$1;
     _snarkjs$1 = (await import('snarkjs'));
@@ -2584,7 +2584,7 @@ function defaultCircuitUrls(baseUrl) {
     };
 }
 /** BN254 scalar field modulus — the prime the circuit's signals live in. */
-const FIELD_SIZE$2 = 21888242871839275222246405745257275088548364400416034343698204186575808495617n;
+const FIELD_SIZE$1 = 21888242871839275222246405745257275088548364400416034343698204186575808495617n;
 /**
  * Reduce any hex/decimal/byte input to a decimal-string field element in
  * `[0, FIELD_SIZE)`. snarkjs and the `preimagePoK` circuit both want decimal
@@ -2625,9 +2625,9 @@ function toField(value) {
             hex += b.toString(16).padStart(2, "0");
         v = BigInt("0x" + hex);
     }
-    v = v % FIELD_SIZE$2;
+    v = v % FIELD_SIZE$1;
     if (v < 0n)
-        v += FIELD_SIZE$2;
+        v += FIELD_SIZE$1;
     return v.toString();
 }
 /**
@@ -2667,7 +2667,7 @@ async function generateAuthProof(args) {
         salt: saltField,
         ecdsaPub: ecdsaPubField,
     };
-    const snarkjs = await loadSnarkjs$2();
+    const snarkjs = await loadSnarkjs$1();
     const { proof, publicSignals } = await snarkjs.groth16.fullProve(circuitInput, args.circuits.wasmUrl, args.circuits.zkeyUrl);
     return {
         proof: proof,
@@ -2752,6 +2752,7 @@ class HttpClient {
     baseUrl;
     apiKey;
     getSessionToken;
+    onUnauthorized;
     fetchFn;
     constructor(opts) {
         if (!opts?.baseUrl)
@@ -2759,6 +2760,7 @@ class HttpClient {
         this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
         this.apiKey = opts.apiKey ?? null;
         this.getSessionToken = opts.getSessionToken ?? (() => null);
+        this.onUnauthorized = opts.onUnauthorized ?? null;
         const f = opts.fetch ?? globalThis.fetch;
         if (typeof f !== "function") {
             throw new Error("HttpClient: `globalThis.fetch` is unavailable; pass an explicit `fetch`.");
@@ -2788,10 +2790,13 @@ class HttpClient {
     post(path, body) {
         return this.request("POST", path, body);
     }
+    patch(path, body) {
+        return this.request("PATCH", path, body);
+    }
     del(path, body) {
         return this.request("DELETE", path, body);
     }
-    async request(method, path, body) {
+    async request(method, path, body, allowRecovery = true) {
         const url = path.startsWith("http") ? path : `${this.baseUrl}${path.startsWith("/") ? "" : "/"}${path}`;
         const init = { method };
         if (body !== undefined) {
@@ -2799,6 +2804,15 @@ class HttpClient {
             init.body = JSON.stringify(body);
         }
         const res = await this.fetch(url, init);
+        // Stale session: try to silently re-auth and replay the request once.
+        // `allowRecovery` is cleared on the retry so a still-401 response (e.g.
+        // recovery minted a token the endpoint still rejects) can't loop.
+        if (res.status === 401 && allowRecovery && this.onUnauthorized && this.getSessionToken()) {
+            const recovered = await this.onUnauthorized();
+            if (recovered) {
+                return this.request(method, path, body, false);
+            }
+        }
         let parsed = null;
         try {
             parsed = await res.json();
@@ -3028,6 +3042,44 @@ class ZkAuth {
      */
     async login(username, password, opts = {}) {
         const identity = await deriveIdentity(username, password);
+        return this.proveAndStore(username, identity, opts);
+    }
+    /**
+     * Silently re-authenticate the current user without prompting for a
+     * password. Only possible while the client is **unlocked** — i.e. the
+     * derived {@link ZkIdentity} (secret + keypairs) is still in memory from a
+     * prior `login()`/`unlock()`. Re-runs the full challenge→proof→authenticate
+     * dance with that in-memory identity and swaps in the fresh token.
+     *
+     * Returns `true` if a new session was minted, `false` if recovery isn't
+     * possible (no active user, or locked — the identity was never derived or
+     * was lost on reload). A `false` result is the app's cue to send the user
+     * back to the login screen.
+     *
+     * Used automatically by the {@link Client} when a token-gated request comes
+     * back `401` (stale/expired token), so transient session expiry self-heals
+     * instead of surfacing errors mid-session.
+     */
+    async recover() {
+        const username = this.deps.session.username;
+        const identity = this.deps.session.identity;
+        if (!username || !identity)
+            return false;
+        try {
+            await this.proveAndStore(username, identity, {});
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Shared sign-in core: prove knowledge of `identity` against a fresh
+     * challenge and persist the resulting session + identity. Used by both
+     * `login()` (identity derived from a password) and `recover()` (identity
+     * already in memory).
+     */
+    async proveAndStore(username, identity, opts) {
         const ecdsaPubHex = await exportPublicKeyHex(identity.ecdsaKeyPair.publicKey);
         const challenge = await this.deps.auth.getChallenge(username);
         const { proof, publicSignals, commitment } = await generateAuthProof({
@@ -3184,144 +3236,6 @@ class StorageCipher {
     }
 }
 
-/**
- * `client.storage` — per-user persistent storage backed by the accelerator's
- * personal space.
- *
- *   await client.storage.set('todos', id, { title, completed })
- *   const todo = await client.storage.get('todos', id)
- *   const ids  = await client.storage.list('todos')
- *   await client.storage.delete('todos', id)
- *   const off  = client.storage.on('change', e => …)   // realtime, cross-device
- *
- * A *collection* is a key namespace within the user's space; the stored key is
- * `${collection}/${id}`. Operations are authorized by the user's session token
- * (stamped on every request by {@link HttpClient}) — no per-op Groth16 proof.
- *
- * Values are encrypted at rest by default ({@link StorageCipher}, an AES-GCM
- * key derived from the ZK identity); pass `{ encrypt: false }` to store
- * plaintext. The realtime feed rides the personal space's own websocket, so no
- * separate transport is involved.
- *
- * `query()` is intentionally deferred — see the SDK overhaul plan.
- */
-class StorageNamespace {
-    deps;
-    cipher = null;
-    cipherIdentity = null;
-    constructor(deps) {
-        this.deps = deps;
-    }
-    /** Store `value` under `collection`/`id` (encrypted at rest by default). */
-    async set(collection, id, value, opts) {
-        const encrypt = opts?.encrypt !== false;
-        const stored = encrypt ? await this.getCipher().encrypt(value) : value;
-        await this.deps.http.post(this.kvPath(collection, id), { value: stored });
-    }
-    /** Fetch the value at `collection`/`id`, or `null` if absent. */
-    async get(collection, id) {
-        const res = await this.deps.http.post(`${this.kvPath(collection, id)}/get`, {});
-        return this.decode(res.value);
-    }
-    /** Delete `collection`/`id`. Returns whether the key existed. */
-    async delete(collection, id) {
-        const res = await this.deps.http.del(this.kvPath(collection, id), {});
-        return Boolean(res.existed);
-    }
-    /** List the ids present in `collection`. */
-    async list(collection) {
-        const res = await this.deps.http.post(this.spacePath("/list"), {});
-        const prefix = `${collection}/`;
-        return (res.keys ?? [])
-            .filter((k) => k.startsWith(prefix))
-            .map((k) => k.slice(prefix.length));
-    }
-    /** Reserved — server-side query is deferred (see the overhaul plan). */
-    async query(_collection, _filter) {
-        throw new Error("client.storage.query is not implemented yet (deferred in the SDK overhaul).");
-    }
-    /**
-     * Subscribe to realtime changes to this user's data across devices. Opens
-     * the personal space's websocket and decrypts each change before handing
-     * it to `handler`. Returns an unsubscribe function.
-     *
-     * Requires a `WebSocket` global (browsers; Node 22+ or a `ws` shim).
-     */
-    on(event, handler) {
-        if (event !== "change")
-            throw new Error(`client.storage: unknown event "${event}"`);
-        const WS = globalThis.WebSocket;
-        if (typeof WS !== "function") {
-            throw new Error("client.storage.on: no `WebSocket` global available in this runtime.");
-        }
-        const token = this.deps.session.token;
-        if (!token)
-            throw new Error("client.storage.on: not signed in.");
-        const url = `${this.deps.wsBaseUrl}/api/personal/${encodeURIComponent(this.commitment())}/websocket?session=${encodeURIComponent(token)}`;
-        const socket = new WS(url);
-        socket.addEventListener("message", (ev) => {
-            void this.dispatchChange(ev.data, handler);
-        });
-        return () => {
-            try {
-                socket.close();
-            }
-            catch { /* already closed */ }
-        };
-    }
-    // -------------------------------------------------------------------------
-    // Internals
-    // -------------------------------------------------------------------------
-    async dispatchChange(raw, handler) {
-        let frame;
-        try {
-            frame = typeof raw === "string" ? JSON.parse(raw) : raw;
-        }
-        catch {
-            return;
-        }
-        if (!frame || frame._t !== "change" || typeof frame.key !== "string")
-            return;
-        const slash = frame.key.indexOf("/");
-        if (slash < 0)
-            return;
-        const collection = frame.key.slice(0, slash);
-        const id = frame.key.slice(slash + 1);
-        const data = frame.op === "set" ? await this.decode(frame.value) : null;
-        handler({ collection, id, type: frame.op, data });
-    }
-    /** Decode a stored value: decrypt envelopes, pass plaintext through. */
-    async decode(value) {
-        if (value == null)
-            return null;
-        if (StorageCipher.isEnvelope(value))
-            return this.getCipher().decrypt(value);
-        return value;
-    }
-    commitment() {
-        const c = this.deps.session.commitment;
-        if (!c)
-            throw new Error("client.storage: not signed in — call client.auth.zk.login() first.");
-        return c;
-    }
-    spacePath(suffix) {
-        return `/api/personal/${encodeURIComponent(this.commitment())}${suffix}`;
-    }
-    kvPath(collection, id) {
-        const key = `${collection}/${id}`;
-        return this.spacePath(`/kv/${encodeURIComponent(key)}`);
-    }
-    /** The at-rest cipher for the current identity (re-derived if it changes). */
-    getCipher() {
-        const identity = this.deps.session.requireIdentity();
-        if (this.cipher && this.cipherIdentity === identity)
-            return this.cipher;
-        this.cipher = new StorageCipher(identity.secretHex, identity.saltHex);
-        this.cipherIdentity = identity;
-        return this.cipher;
-    }
-}
-
 /**
  * Pure WebSocket transport — owns the socket lifecycle and nothing else.
  *
@@ -3337,11 +3251,31 @@ class StorageNamespace {
  *   - Emit lifecycle events (CONNECTED / DISCONNECTED / RECONNECTING / ERROR)
  *     plus raw inbound MESSAGE events
  */
+/** Monotonic source of unique transport ids when a caller doesn't supply one. */
+let __wsInstanceSeq = 0;
 class WSTransport extends EventCore {
-    emit = EventCore.emit;
-    on = EventCore.on;
-    off = EventCore.off;
+    /**
+     * Per-instance event scope. `EventCore` is a process-global static emitter,
+     * so without namespacing every WSTransport would hear every other one's
+     * frames. We prefix each event with this transport's `id` and expose
+     * `on`/`off`/`emit` that scope transparently — callers still use the plain
+     * `EventCoreEvents` enum and only ever see their own connection's events.
+     */
+    id;
+    emit = (event, data) => {
+        EventCore.emit(this.scopedEvent(event), data);
+    };
+    on = (event, handler) => {
+        EventCore.on(this.scopedEvent(event), handler);
+    };
+    off = (event, handler) => {
+        EventCore.off(this.scopedEvent(event), handler);
+    };
+    scopedEvent(event) {
+        return `${this.id}:${event}`;
+    }
     url;
+    urlProvider;
     socket = null;
     _isConnected = false;
     _isConnecting = false;
@@ -3354,16 +3288,29 @@ class WSTransport extends EventCore {
     // Outbound queue (raw frame strings — already serialized by caller)
     outboundQueue = [];
     maxQueueSize;
+    // Heartbeat / liveness state
+    heartbeatInterval;
+    heartbeatTimeout;
+    pingFrame;
+    pongFrame;
+    heartbeatTimer = null;
+    pongTimer = null;
     constructor(opts) {
         super();
         if (!opts || !opts.url) {
             throw new Error("WSTransport: `url` is required");
         }
         this.url = opts.url;
+        this.urlProvider = opts.urlProvider;
+        this.id = opts.id ?? `ws${++__wsInstanceSeq}`;
         this.autoReconnect = opts.autoReconnect ?? true;
         this.reconnectDelay = opts.reconnectDelay ?? 3000;
         this.maxReconnectAttempts = opts.maxReconnectAttempts ?? 5;
         this.maxQueueSize = opts.maxQueueSize ?? 100;
+        this.heartbeatInterval = opts.heartbeatInterval ?? 30000;
+        this.heartbeatTimeout = opts.heartbeatTimeout ?? 10000;
+        this.pingFrame = opts.pingFrame ?? "ping";
+        this.pongFrame = opts.pongFrame ?? "pong";
     }
     /** Open the socket. Resolves when CONNECTED fires. Rejects on first error. */
     async connect() {
@@ -3371,6 +3318,18 @@ class WSTransport extends EventCore {
             throw new Error("WSTransport: already connected or connecting");
         }
         this._isConnecting = true;
+        // On a RECONNECT, refresh the URL (the baked-in single-use ticket is spent).
+        // The first connect uses `url` as-is. If the provider throws (e.g. can't
+        // mint a ticket), surface it and let scheduleReconnect retry.
+        if (this.urlProvider && this.reconnectAttempts > 0) {
+            try {
+                this.url = await this.urlProvider();
+            }
+            catch (err) {
+                this._isConnecting = false;
+                throw err;
+            }
+        }
         return new Promise((resolve, reject) => {
             try {
                 const socket = new WebSocket(this.url);
@@ -3381,9 +3340,19 @@ class WSTransport extends EventCore {
                     this.reconnectAttempts = 0;
                     this.emit(EventCoreEvents.CONNECTED, undefined);
                     this.flushQueue();
+                    this.startHeartbeat();
                     resolve();
                 };
                 socket.onmessage = (event) => {
+                    // Heartbeat ack — swallow it (don't surface as a MESSAGE) and clear
+                    // the liveness deadline. The layer above never sees keep-alive frames.
+                    if (event.data === this.pongFrame) {
+                        if (this.pongTimer) {
+                            clearTimeout(this.pongTimer);
+                            this.pongTimer = null;
+                        }
+                        return;
+                    }
                     // Raw inbound frame — layer above is responsible for parsing.
                     this.emit(EventCoreEvents.MESSAGE, event.data);
                 };
@@ -3398,6 +3367,7 @@ class WSTransport extends EventCore {
                     const wasConnected = this._isConnected;
                     this._isConnected = false;
                     this._isConnecting = false;
+                    this.stopHeartbeat();
                     this.emit(EventCoreEvents.DISCONNECTED, undefined);
                     if (this.autoReconnect && wasConnected) {
                         this.scheduleReconnect();
@@ -3416,6 +3386,7 @@ class WSTransport extends EventCore {
             clearTimeout(this.reconnectTimeout);
             this.reconnectTimeout = null;
         }
+        this.stopHeartbeat();
         this.autoReconnect = false;
         if (this.socket) {
             try {
@@ -3446,6 +3417,78 @@ class WSTransport extends EventCore {
     queuedFrames() { return this.outboundQueue.length; }
     reconnectAttemptCount() { return this.reconnectAttempts; }
     // -- internals -------------------------------------------------------------
+    /** Begin the keep-alive loop (no-op when disabled). */
+    startHeartbeat() {
+        if (this.heartbeatInterval <= 0)
+            return;
+        this.stopHeartbeat();
+        this.heartbeatTimer = setInterval(() => this.sendHeartbeat(), this.heartbeatInterval);
+    }
+    /** Stop the keep-alive loop and clear any pending liveness deadline. */
+    stopHeartbeat() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+        if (this.pongTimer) {
+            clearTimeout(this.pongTimer);
+            this.pongTimer = null;
+        }
+    }
+    /**
+     * Send one ping and arm a liveness deadline. If no `pongFrame` arrives before
+     * `heartbeatTimeout`, the connection is considered dead and we force a
+     * reconnect — this is what catches a silently-dropped TCP connection that
+     * never fired `onclose` (the failure mode that "loses connection with the
+     * Accelerator" on long sessions).
+     */
+    sendHeartbeat() {
+        if (!this._isConnected || !this.socket)
+            return;
+        try {
+            this.socket.send(this.pingFrame);
+        }
+        catch {
+            this.forceReconnect();
+            return;
+        }
+        // A still-pending deadline means the previous pong never came back.
+        if (this.pongTimer)
+            return;
+        this.pongTimer = setTimeout(() => {
+            this.pongTimer = null;
+            this.forceReconnect();
+        }, this.heartbeatTimeout);
+    }
+    /**
+     * Tear down a connection we believe is dead and kick off reconnect, without
+     * waiting on the OS/browser to eventually fire `onclose` (which a half-open
+     * socket may never do). We detach the handlers first so the normal close path
+     * can't double-fire the reconnect.
+     */
+    forceReconnect() {
+        this.stopHeartbeat();
+        const sock = this.socket;
+        const wasConnected = this._isConnected;
+        this.socket = null;
+        this._isConnected = false;
+        this._isConnecting = false;
+        if (sock) {
+            sock.onopen = null;
+            sock.onmessage = null;
+            sock.onerror = null;
+            sock.onclose = null;
+            try {
+                sock.close();
+            }
+            catch { /* already gone */ }
+        }
+        this.emit(EventCoreEvents.ERROR, new Error("WSTransport: heartbeat timeout"));
+        this.emit(EventCoreEvents.DISCONNECTED, undefined);
+        if (this.autoReconnect && wasConnected) {
+            this.scheduleReconnect();
+        }
+    }
     scheduleReconnect() {
         if (this.maxReconnectAttempts > 0 &&
             this.reconnectAttempts >= this.maxReconnectAttempts) {
@@ -3459,7 +3502,12 @@ class WSTransport extends EventCore {
                 await this.connect();
             }
             catch {
-                // scheduleReconnect will fire again from onclose
+                // A failed reconnect never opened the socket, so its `onclose` won't
+                // re-schedule (that path is guarded by `wasConnected`). Re-schedule here
+                // so we keep retrying (with a fresh ticket each time) until we succeed
+                // or hit the attempt cap.
+                if (this.autoReconnect)
+                    this.scheduleReconnect();
             }
         }, this.reconnectDelay);
     }
@@ -3481,473 +3529,160 @@ class WSTransport extends EventCore {
 }
 
 /**
- * An end-to-end-encrypted communication session for one local identity
- * (`myId`) talking to an arbitrary set of peers. Wraps `KeyStore` +
- * per-pair `DoubleRatchet` instances and owns the protocol bookkeeping
- * (handshake reciprocation, dedup, role assignment, broadcast fan-out,
- * recipient filtering) so application code doesn't have to.
+ * `client.kv` — per-user key/value storage backed by the accelerator's personal
+ * space.
  *
- * Transport-agnostic by design: the Session never touches a WebSocket
- * (or HTTP, or anything else). Application code:
- *   - calls `session.encrypt(text)` and gets back an array of frames it
- *     ships over whatever transport it has;
- *   - calls `session.receive(frame)` with each inbound frame and acts on
- *     the typed result (plaintext, handshake-done, ignored).
+ *   await client.kv.set('todos', id, { title, completed })
+ *   const todo = await client.kv.get('todos', id)
+ *   const ids  = await client.kv.list('todos')
+ *   await client.kv.delete('todos', id)
+ *   const off  = client.kv.on('change', e => …)   // realtime, cross-device
  *
- * Frames are plain JSON objects with the same shape the existing chat
- * protocol uses (`{ keyExchange: {...} }` and `{ cipherMessage: {...} }`),
- * so this can drop into a chat app without changing the wire format.
+ * A *collection* is a key namespace within the user's space; the stored key is
+ * `${collection}/${id}`. Operations are authorized by the user's session token
+ * (stamped on every request by {@link HttpClient}) — no per-op Groth16 proof.
+ *
+ * Values are encrypted at rest by default ({@link StorageCipher}, an AES-GCM
+ * key derived from the ZK identity); pass `{ encrypt: false }` to store
+ * plaintext. The realtime feed rides the personal space's websocket over a
+ * {@link WSTransport} (heartbeat keep-alive + auto-reconnect, event-namespaced
+ * so it doesn't cross wires with chat/space transports).
+ *
+ * For **files** (blobs), use `client.storage` instead — `client.kv` is for
+ * small structured values. `query()` is intentionally deferred.
  */
-// ---------------------------------------------------------------------------
-// EncryptedSession
-// ---------------------------------------------------------------------------
-class EncryptedSession {
-    myId;
-    keyStore;
-    /** One DoubleRatchet per peer pair. */
-    ratchets = new Map();
-    /** Peers we've already sent our keyExchange to in this Session. */
-    sentHandshakeTo = new Set();
-    /** Resolved when own keys are generated and ready to use. */
-    _ready;
-    _resolveReady;
-    _initialized = false;
-    constructor(opts) {
-        if (!opts || !opts.myId) {
-            throw new Error("EncryptedSession: `myId` is required");
-        }
-        this.myId = opts.myId;
-        this.keyStore = KeyStore.getInstance();
-        this._ready = new Promise((resolve) => {
-            this._resolveReady = resolve;
-        });
+class KvNamespace {
+    deps;
+    cipher = null;
+    cipherIdentity = null;
+    constructor(deps) {
+        this.deps = deps;
     }
-    /** A promise that resolves once `initialize()` has completed. */
-    get ready() {
-        return this._ready;
+    /** Store `value` under `collection`/`id` (encrypted at rest by default). */
+    async set(collection, id, value, opts) {
+        const encrypt = opts?.encrypt !== false;
+        const stored = encrypt ? await this.getCipher().encrypt(value) : value;
+        await this.deps.http.post(this.kvPath(collection, id), { value: stored });
     }
-    /** Our local identifier. */
-    get id() {
-        return this.myId;
+    /** Fetch the value at `collection`/`id`, or `null` if absent. */
+    async get(collection, id) {
+        const res = await this.deps.http.post(`${this.kvPath(collection, id)}/get`, {});
+        return this.decode(res.value);
     }
-    /**
-     * Generate this client's ECDH + ECDSA keypair (idempotent — safe to call
-     * multiple times across reconnects; only the first call generates).
-     */
-    async initialize() {
-        if (this._initialized)
-            return;
-        if (!this.keyStore.getKeyPair(this.myId)) {
-            await this.keyStore.generateOwnKeyPair(this.myId);
-        }
-        this._initialized = true;
-        this._resolveReady();
+    /** Delete `collection`/`id`. Returns whether the key existed. */
+    async delete(collection, id) {
+        const res = await this.deps.http.del(this.kvPath(collection, id), {});
+        return Boolean(res.existed);
     }
-    /**
-     * Build the keyExchange frame this client should send to peers when it
-     * comes online. Application is responsible for actually transmitting it
-     * (e.g. ws.send(JSON.stringify(frame))).
-     */
-    async getOwnKeyExchange() {
-        await this._ready;
-        const ownEcdh = this.keyStore.getKeyPair(this.myId);
-        const ownEcdsa = this.keyStore.getAuthKeyPair(this.myId);
-        if (!ownEcdh || !ownEcdsa) {
-            throw new Error("EncryptedSession.getOwnKeyExchange: keys not initialized");
-        }
-        return {
-            keyExchange: {
-                type: "handshake",
-                userId: this.myId,
-                ecdhPublicKey: await exportJwkBase64(ownEcdh.publicKey),
-                ecdsaPublicKey: await exportJwkBase64(ownEcdsa.publicKey),
-            },
-        };
+    /** List the ids present in `collection`. */
+    async list(collection) {
+        const res = await this.deps.http.post(this.spacePath("/list"), {});
+        const prefix = `${collection}/`;
+        return (res.keys ?? [])
+            .filter((k) => k.startsWith(prefix))
+            .map((k) => k.slice(prefix.length));
+    }
+    /** Reserved — server-side query is deferred (see the overhaul plan). */
+    async query(_collection, _filter) {
+        throw new Error("client.kv.query is not implemented yet (deferred in the SDK overhaul).");
     }
     /**
-     * Encrypt a plaintext to every peer we currently have a ratchet for, and
-     * return one cipherMessage frame per recipient. The application sends
-     * each frame over its transport.
+     * Subscribe to realtime changes to this user's data across devices. Opens
+     * the personal space's websocket and decrypts each change before handing
+     * it to `handler`. Returns an unsubscribe function.
      *
-     * If there are no peers yet (or all peers are still mid-handshake), the
-     * returned array may be empty — the caller should typically render the
-     * outgoing message locally in that case (since there's no one to send
-     * it to yet).
+     * Requires a `WebSocket` global (browsers; Node 22+ or a `ws` shim).
      */
-    async encrypt(plaintext) {
-        await this._ready;
-        const frames = [];
-        for (const peerId of this.ratchets.keys()) {
-            const ratchet = this.ratchets.get(peerId);
-            const sessionId = this._sessionIdFor(peerId);
-            const cipherMessage = await ratchet.encrypt(plaintext, 
-            /* newDhKey */ false, this.myId, peerId, sessionId, "specific");
-            frames.push({ cipherMessage });
+    on(event, handler) {
+        if (event !== "change")
+            throw new Error(`client.kv: unknown event "${event}"`);
+        if (typeof globalThis.WebSocket !== "function") {
+            throw new Error("client.kv.on: no `WebSocket` global available in this runtime.");
         }
-        return frames;
+        const token = this.deps.session.token;
+        if (!token)
+            throw new Error("client.kv.on: not signed in.");
+        const commitment = this.commitment();
+        const url = `${this.deps.wsBaseUrl}/api/personal/${encodeURIComponent(commitment)}/websocket?session=${encodeURIComponent(token)}`;
+        // Ride a WSTransport rather than a bare socket: it keeps the (otherwise
+        // idle) personal-space feed warm with heartbeat pings, auto-reconnects
+        // if it drops, and namespaces its events by `id` so this feed never
+        // crosses wires with chat/space transports on the shared EventCore bus.
+        const transport = new WSTransport({ url, id: `personal:${commitment}` });
+        const onMessage = (e) => {
+            void this.dispatchChange(e.detail, handler);
+        };
+        transport.on(EventCoreEvents.MESSAGE, onMessage);
+        // Fire-and-forget: the realtime feed is best-effort, and the transport
+        // queues nothing it needs before CONNECTED (server→client only).
+        void transport.connect();
+        return () => {
+            transport.off(EventCoreEvents.MESSAGE, onMessage);
+            transport.disconnect();
+        };
     }
-    /**
-     * Hand an inbound frame to the session. Returns a typed result the
-     * application acts on.
-     *
-     *   - `kind: 'plaintext'`         — decrypted; render `result.text`
-     *   - `kind: 'handshake'`         — a peer's keys are now stored, and if
-     *                                   `result.outbound` is set, send it
-     *   - `kind: 'ignored'`           — not for us, malformed, duplicate, etc.
-     *
-     * Calling code should always handle `'ignored'` (no UI side effect).
-     */
-    async receive(frame) {
-        await this._ready;
-        // -- handshake frame -----------------------------------------------------
-        if (isKeyExchangeFrame(frame)) {
-            const kx = frame.keyExchange;
-            const peerId = kx.userId;
-            if (peerId === this.myId) {
-                return { kind: "ignored", reason: "own keyExchange echo" };
-            }
-            const isNew = !this.ratchets.has(peerId);
-            // (Re-)store the peer's pubkeys + (re-)build the ratchet if needed.
-            const peerEcdh = await importJwkBase64(kx.ecdhPublicKey, "ECDH");
-            const peerEcdsa = await importJwkBase64(kx.ecdsaPublicKey, "ECDSA");
-            await this.keyStore.storeRemotePublicKeys(peerId, peerEcdh, peerEcdsa);
-            if (isNew) {
-                const isClient = this.myId < peerId;
-                const ratchet = new DoubleRatchet(this.myId, peerId, "specific", isClient);
-                await ratchet.initializeSession(isClient);
-                this.ratchets.set(peerId, ratchet);
-            }
-            // Reciprocate exactly once per peer per session lifetime.
-            let outbound = null;
-            if (isNew && !this.sentHandshakeTo.has(peerId)) {
-                outbound = await this.getOwnKeyExchange();
-                this.sentHandshakeTo.add(peerId);
-            }
-            return { kind: "handshake", peerId, outbound };
+    // -------------------------------------------------------------------------
+    // Internals
+    // -------------------------------------------------------------------------
+    async dispatchChange(raw, handler) {
+        let frame;
+        try {
+            frame = typeof raw === "string" ? JSON.parse(raw) : raw;
         }
-        // -- ciphertext frame ----------------------------------------------------
-        if (isCipherFrame(frame)) {
-            const cipherMessage = frame.cipherMessage;
-            const header = cipherMessage?.header;
-            if (!header) {
-                return { kind: "ignored", reason: "cipherMessage has no header" };
-            }
-            if (header.senderId === this.myId) {
-                return { kind: "ignored", reason: "own outbound echo" };
-            }
-            if (header.recipientId && header.recipientId !== this.myId) {
-                return { kind: "ignored", reason: "addressed to a different peer" };
-            }
-            const ratchet = this.ratchets.get(header.senderId);
-            if (!ratchet) {
-                return {
-                    kind: "ignored",
-                    reason: `no ratchet with sender ${header.senderId} (handshake hasn't completed)`,
-                };
-            }
-            const isClient = this.myId < header.senderId;
-            let text;
-            try {
-                text = await ratchet.decrypt(cipherMessage, isClient);
-            }
-            catch (err) {
-                // DoubleRatchet's wallclock-based replay-protection check throws
-                // "CipherMessage too old, possible replay attack" for any frame
-                // older than 5 minutes. Real replays still fail downstream because
-                // the message key has been consumed; the wallclock check is a
-                // defense-in-depth heuristic, not a security boundary. Treating it
-                // as `ignored` lets the channel survive legacy backlog replays and
-                // CF WS-idle-timeout reconnect cycles without spamming the
-                // channel's ERROR stream.
-                const msg = err instanceof Error ? err.message : String(err);
-                if (msg.includes("too old") || msg.includes("replay attack")) {
-                    return { kind: "ignored", reason: `stale cipherMessage rejected: ${msg}` };
-                }
-                throw err;
-            }
-            return { kind: "plaintext", from: header.senderId, text, cipherMessage };
+        catch {
+            return;
         }
-        return { kind: "ignored", reason: "unknown frame type" };
+        if (!frame || frame._t !== "change" || typeof frame.key !== "string")
+            return;
+        const slash = frame.key.indexOf("/");
+        if (slash < 0)
+            return;
+        const collection = frame.key.slice(0, slash);
+        const id = frame.key.slice(slash + 1);
+        const data = frame.op === "set" ? await this.decode(frame.value) : null;
+        handler({ collection, id, type: frame.op, data });
     }
-    // -- introspection ---------------------------------------------------------
-    /** List of peer ids we have an established ratchet for. */
-    peers() {
-        return Array.from(this.ratchets.keys());
+    /** Decode a stored value: decrypt envelopes, pass plaintext through. */
+    async decode(value) {
+        if (value == null)
+            return null;
+        if (StorageCipher.isEnvelope(value))
+            return this.getCipher().decrypt(value);
+        return value;
     }
-    /** Has the handshake completed for this peer? */
-    hasRatchetFor(peerId) {
-        return this.ratchets.has(peerId);
+    commitment() {
+        const c = this.deps.session.commitment;
+        if (!c)
+            throw new Error("client.kv: not signed in — call client.auth.zk.login() first.");
+        return c;
     }
-    /**
-     * Tear down a peer's ratchet (e.g. when they leave the room). The peer's
-     * stored keys remain in `KeyStore` so a fresh handshake can be set up
-     * later without re-fetching them, but the ratchet state is dropped.
-     */
-    forgetPeer(peerId) {
-        this.ratchets.delete(peerId);
-        this.sentHandshakeTo.delete(peerId);
+    spacePath(suffix) {
+        return `/api/personal/${encodeURIComponent(this.commitment())}${suffix}`;
     }
-    // -- internals -------------------------------------------------------------
-    /** Deterministic per-pair session id — same string on both sides. */
-    _sessionIdFor(peerId) {
-        return [this.myId, peerId].sort().join(":");
+    kvPath(collection, id) {
+        const key = `${collection}/${id}`;
+        return this.spacePath(`/kv/${encodeURIComponent(key)}`);
+    }
+    /** The at-rest cipher for the current identity (re-derived if it changes). */
+    getCipher() {
+        const identity = this.deps.session.requireIdentity();
+        if (this.cipher && this.cipherIdentity === identity)
+            return this.cipher;
+        this.cipher = new StorageCipher(identity.secretHex, identity.saltHex);
+        this.cipherIdentity = identity;
+        return this.cipher;
     }
-}
-// ---------------------------------------------------------------------------
-// Helpers — JWK <-> base64 string for key transport
-// ---------------------------------------------------------------------------
-async function exportJwkBase64(key) {
-    const jwk = await crypto.subtle.exportKey("jwk", key);
-    return btoa(JSON.stringify(jwk));
-}
-async function importJwkBase64(b64, type) {
-    const jwk = JSON.parse(atob(b64));
-    const algorithm = type === "ECDH"
-        ? { name: "ECDH", namedCurve: "P-384" }
-        : { name: "ECDSA", namedCurve: "P-384" };
-    const usages = type === "ECDH" ? [] : ["verify"];
-    return await crypto.subtle.importKey("jwk", jwk, algorithm, true, usages);
-}
-// ---------------------------------------------------------------------------
-// Type guards
-// ---------------------------------------------------------------------------
-function isKeyExchangeFrame(frame) {
-    const kx = frame.keyExchange;
-    if (!kx || typeof kx !== "object")
-        return false;
-    const k = kx;
-    return (typeof k.userId === "string" &&
-        typeof k.ecdhPublicKey === "string" &&
-        typeof k.ecdsaPublicKey === "string");
-}
-function isCipherFrame(frame) {
-    const cm = frame.cipherMessage;
-    if (!cm || typeof cm !== "object")
-        return false;
-    const m = cm;
-    return Boolean(m.header && m.ciphertext && m.nonce);
 }
 
 /**
- * BroadcastChannel — a turnkey end-to-end encrypted channel for multi-peer
- * "room"-style apps (e.g. a chat). Wires together:
- *
- *   - `WSTransport` for socket lifecycle, reconnect, and offline frame queue
- *   - `EncryptedSession` for per-peer Double Ratchet state, handshake
- *     reciprocation, fan-out encryption, and recipient filtering
- *
- * The host app only deals with high-level events and method calls; it never
- * touches `new WebSocket(...)` or builds cipherMessage frames by hand.
- *
- * Wire protocol (kept compatible with the existing chat protocol so this
- * drops into the deployed Accelerator without server changes):
+ * Wire types for the storage layer.
  *
- *   outbound: `{ keyExchange: {...} }`      — produced by us on `announce()`
- *             `{ cipherMessage: {...} }`    — produced by `send(text)`,
- *                                              one frame per peer
- *             arbitrary JSON                — sent via `sendRaw(obj)`
- *
- *   inbound:  `{ keyExchange: {...} }`      — routed into EncryptedSession;
- *                                              emits `peer_handshake`
- *             `{ cipherMessage: {...} }`    — decrypted; emits `message`
- *             anything else                 — passes through as `raw_frame`
- *                                              (the app decides what to do)
- *
- * **Event scoping.** Unlike `Network`, BroadcastChannel uses a per-instance
- * `EventTarget`, so two channels (e.g. two rooms in the same app) don't
- * cross-contaminate each other's events.
- *
- * Note: this class shadows the `BroadcastChannel` Web API global (cross-tab
- * messaging) only when imported by name. They're unrelated.
- */
-// ---------------------------------------------------------------------------
-// Event names
-// ---------------------------------------------------------------------------
-/**
- * Event names BroadcastChannel emits. Lifecycle events reuse the
- * `EventCoreEvents` string values (`connected`, `disconnected`, etc.) so
- * apps can use shared constants if they want. Channel-specific events are
- * prefixed `channel:` to avoid colliding with other event systems in the
- * same app.
- */
-const BroadcastChannelEvents = {
-    CONNECTED: EventCoreEvents.CONNECTED,
-    DISCONNECTED: EventCoreEvents.DISCONNECTED,
-    RECONNECTING: EventCoreEvents.RECONNECTING,
-    ERROR: EventCoreEvents.ERROR,
-    /** A peer's ratchet is now ready. `detail.peerId` is the peer's id. */
-    PEER_HANDSHAKE: "channel:peer_handshake",
-    /** Decrypted message. `detail` is `{ from, text, cipherMessage }`. */
-    MESSAGE: "channel:message",
-    /** Inbound frame BroadcastChannel didn't recognize. App handles it. */
-    RAW_FRAME: "channel:raw_frame",
-};
-// ---------------------------------------------------------------------------
-// BroadcastChannel
-// ---------------------------------------------------------------------------
-class BroadcastChannel {
-    transport;
-    session;
-    myId;
-    autoAnnounce;
-    announced = false;
-    /** Per-instance EventTarget — events do NOT leak across BroadcastChannels. */
-    events = new EventTarget();
-    constructor(opts) {
-        if (!opts || !opts.myId) {
-            throw new Error("BroadcastChannel: `myId` is required");
-        }
-        this.myId = opts.myId;
-        this.autoAnnounce = opts.autoAnnounce ?? false;
-        this.transport = new WSTransport(opts);
-        this.session = new EncryptedSession({ myId: opts.myId });
-        // Pass-through lifecycle events from the transport. `EventCore.on` is
-        // static so it routes back through the shared singleton; we bridge it
-        // into our instance-scoped event target.
-        this.transport.on(EventCoreEvents.CONNECTED, () => {
-            // Reset the announce flag on every (re)connect. CF Workers WebSockets
-            // hit an idle timeout and force reconnects; without resetting, the
-            // SDK would short-circuit announce() and any peer who joined the
-            // room after our last announce would never see our pubkey.
-            this.announced = false;
-            this.emit(BroadcastChannelEvents.CONNECTED);
-            if (this.autoAnnounce) {
-                void this.announce();
-            }
-        });
-        this.transport.on(EventCoreEvents.DISCONNECTED, () => {
-            this.emit(BroadcastChannelEvents.DISCONNECTED);
-        });
-        this.transport.on(EventCoreEvents.RECONNECTING, (e) => {
-            this.emit(BroadcastChannelEvents.RECONNECTING, e.detail);
-        });
-        this.transport.on(EventCoreEvents.ERROR, (e) => {
-            this.emit(BroadcastChannelEvents.ERROR, e.detail);
-        });
-        // Route inbound raw frames through our framing/decryption logic.
-        this.transport.on(EventCoreEvents.MESSAGE, (e) => {
-            void this.handleInboundFrame(e.detail);
-        });
-    }
-    // -- event API -------------------------------------------------------------
-    /** Subscribe to a channel event. Handler receives a CustomEvent. */
-    on(event, handler) {
-        this.events.addEventListener(event, handler);
-    }
-    /** Unsubscribe. */
-    off(event, handler) {
-        this.events.removeEventListener(event, handler);
-    }
-    emit(event, detail) {
-        this.events.dispatchEvent(new CustomEvent(event, { detail }));
-    }
-    // -- lifecycle -------------------------------------------------------------
-    /** Generate our keys (idempotent) and open the WebSocket. */
-    async connect() {
-        await this.session.initialize();
-        await this.transport.connect();
-    }
-    /** Close the WebSocket and stop reconnecting. */
-    disconnect() {
-        this.transport.disconnect();
-    }
-    /**
-     * Send our `keyExchange` frame to the room. Idempotent — only sends on the
-     * first call. Call this once your higher-level handshake (e.g. sending a
-     * `{name}` identification frame) has completed.
-     */
-    async announce() {
-        if (this.announced)
-            return;
-        this.announced = true;
-        const frame = await this.session.getOwnKeyExchange();
-        this.transport.send(JSON.stringify(frame));
-    }
-    /**
-     * Encrypt `plaintext` to every peer we have a ratchet with, and send each
-     * cipherMessage as its own WS frame. Returns the number of peers we sent to
-     * (0 if no peers are handshaken yet — in which case the caller should
-     * typically render the message locally for the sender and try again later).
-     */
-    async send(plaintext) {
-        const frames = await this.session.encrypt(plaintext);
-        for (const frame of frames) {
-            this.transport.send(JSON.stringify(frame));
-        }
-        return frames.length;
-    }
-    /**
-     * Send an arbitrary JSON-serializable frame as-is. The app uses this for
-     * any frame that isn't channel-managed (e.g. a chat's `{name}`, `{file}`,
-     * or unencrypted `{message}`).
-     */
-    sendRaw(frame) {
-        this.transport.send(JSON.stringify(frame));
-    }
-    // -- introspection ---------------------------------------------------------
-    /** List of peer ids we have an established ratchet for. */
-    peers() {
-        return this.session.peers();
-    }
-    /** Drop a peer's ratchet (e.g. when they leave the room). */
-    forgetPeer(peerId) {
-        this.session.forgetPeer(peerId);
-    }
-    isConnected() {
-        return this.transport.isConnected();
-    }
-    // -- internals -------------------------------------------------------------
-    async handleInboundFrame(raw) {
-        let parsed;
-        try {
-            parsed = JSON.parse(raw);
-        }
-        catch (err) {
-            this.emit(BroadcastChannelEvents.ERROR, err);
-            return;
-        }
-        if (!parsed || typeof parsed !== "object") {
-            this.emit(BroadcastChannelEvents.RAW_FRAME, parsed);
-            return;
-        }
-        const obj = parsed;
-        // Channel-managed: keyExchange & cipherMessage. Anything else is RAW_FRAME.
-        if ("keyExchange" in obj || "cipherMessage" in obj) {
-            try {
-                const result = await this.session.receive(obj);
-                if (result.kind === "handshake") {
-                    if (result.outbound) {
-                        this.transport.send(JSON.stringify(result.outbound));
-                    }
-                    this.emit(BroadcastChannelEvents.PEER_HANDSHAKE, { peerId: result.peerId });
-                }
-                else if (result.kind === "plaintext") {
-                    this.emit(BroadcastChannelEvents.MESSAGE, {
-                        from: result.from,
-                        text: result.text,
-                        cipherMessage: result.cipherMessage,
-                    });
-                }
-                // `ignored` is intentionally swallowed; subscribe to ERROR for bad frames.
-            }
-            catch (err) {
-                this.emit(BroadcastChannelEvents.ERROR, err);
-            }
-            return;
-        }
-        this.emit(BroadcastChannelEvents.RAW_FRAME, obj);
-    }
-}
-
-/**
- * Wire types for the storage layer.
- *
- * The `FileManifest` is the single piece of metadata the system needs to
- * reassemble a file: per-chunk encryption material, RS parameters, and the
- * SHA-256 content hashes of every shard that belongs to the chunk. With the
- * manifest in hand, a reader can pull each shard from the open content-
- * addressed shard store, decode, decrypt, and concatenate to recover the
- * original bytes.
+ * The `FileManifest` is the single piece of metadata the system needs to
+ * reassemble a file: per-chunk encryption material, RS parameters, and the
+ * SHA-256 content hashes of every shard that belongs to the chunk. With the
+ * manifest in hand, a reader can pull each shard from the open content-
+ * addressed shard store, decode, decrypt, and concatenate to recover the
+ * original bytes.
  *
  * The manifest itself lives inside a `SharedSpaceDO` (Phase B) which gates
  * access by ZK proof + ACL. Shards are stored in the open content-addressed
@@ -4553,6 +4288,8 @@ class FileStorage {
         const fileId = input.fileId ?? generateId();
         const createdAt = Date.now();
         const chunks = [];
+        const totalChunks = Math.max(1, Math.ceil(data.length / this.chunkSize));
+        input.onProgress?.(0, totalChunks);
         // Slicing + encrypting + encoding + uploading is done per-chunk so
         // the peak memory footprint stays at ~chunkSize even for huge files.
         // Within a chunk, the shard uploads are parallelized up to
@@ -4562,6 +4299,7 @@ class FileStorage {
             const end = Math.min(start + this.chunkSize, data.length);
             const plaintext = data.subarray(start, end);
             chunks.push(await this.writeChunk(plaintext, chunkIndex));
+            input.onProgress?.(chunks.length, totalChunks);
             // Stop after one iteration if the file is empty — we still emit a
             // single zero-length chunk so the manifest has a stable shape.
             if (data.length === 0)
@@ -4733,20 +4471,710 @@ class FileStorage {
                 await tasks[idx]();
             }
         }
-        const workers = new Array(Math.min(concurrency, tasks.length))
-            .fill(null)
-            .map(() => nextWorker());
-        await Promise.all(workers);
+        const workers = new Array(Math.min(concurrency, tasks.length))
+            .fill(null)
+            .map(() => nextWorker());
+        await Promise.all(workers);
+    }
+}
+/** Normalize `data` to a flat `Uint8Array`. */
+async function toUint8Array(data) {
+    if (data instanceof Uint8Array)
+        return data;
+    // Blob covers File too (File extends Blob in every runtime we target).
+    const ab = await data.arrayBuffer();
+    return new Uint8Array(ab);
+}
+
+/**
+ * HTTP client for the gated file-manifest store on a SharedSpace
+ * (`/api/spaces/:spaceId/files`).
+ *
+ * A "file" in a space is its **manifest** (per-chunk keys + the SHA-256 of each
+ * global shard). The shard bytes live in the open `/api/shards` store; the
+ * manifest is the capability. This client only moves manifests in/out of the
+ * space's gated store.
+ *
+ * Authorization is **session-based**, consistent with the rest of the
+ * SharedSpace (keyring, websocket): the SDK's credential-stamping `fetch`
+ * (from {@link HttpClient}) attaches the app key + session token, the platform
+ * validates the session and injects a trusted `X-Muhkoo-User-Context`, and the
+ * DO authorizes on that + channel membership. There is no per-op Groth16 proof.
+ *
+ * Wire protocol (server: `SharedSpaceDO`):
+ *   POST   /api/spaces/:spaceId/files            body: { manifest }  → { ok, fileId }
+ *   GET    /api/spaces/:spaceId/files                                → { files: FileStat[] }
+ *   GET    /api/spaces/:spaceId/files/:fileId                        → { manifest }
+ *   DELETE /api/spaces/:spaceId/files/:fileId                        → { ok, existed }
+ */
+class SharedSpaceClient {
+    baseUrl;
+    fetchFn;
+    constructor(opts) {
+        if (!opts?.baseUrl)
+            throw new Error("SharedSpaceClient: `baseUrl` is required");
+        this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+        const f = opts.fetch ?? globalThis.fetch;
+        if (typeof f !== "function") {
+            throw new Error("SharedSpaceClient: `globalThis.fetch` is unavailable; pass an explicit fetch.");
+        }
+        this.fetchFn = f.bind(globalThis);
+    }
+    /** Write a file manifest into the space. Requires space membership. */
+    async writeFileManifest(spaceId, manifest) {
+        const url = `${this.filesBase(spaceId)}`;
+        const res = await this.fetchFn(url, this.jsonRequest("POST", { manifest }));
+        await parseOrThrow$1(res, `writeFileManifest(${manifest.id})`);
+    }
+    /** Read a file manifest by id. Requires space membership. */
+    async readFileManifest(spaceId, fileId) {
+        const url = `${this.filesBase(spaceId)}/${encodeURIComponent(fileId)}`;
+        const res = await this.fetchFn(url, this.jsonRequest("GET"));
+        const data = await parseOrThrow$1(res, `readFileManifest(${fileId})`);
+        return data.manifest;
+    }
+    /** Delete a file manifest by id. Requires space membership. */
+    async deleteFileManifest(spaceId, fileId) {
+        const url = `${this.filesBase(spaceId)}/${encodeURIComponent(fileId)}`;
+        const res = await this.fetchFn(url, this.jsonRequest("DELETE"));
+        const data = await parseOrThrow$1(res, `deleteFileManifest(${fileId})`);
+        return data.existed;
+    }
+    /** List file summaries in the space. Requires space membership. */
+    async listFiles(spaceId) {
+        const url = `${this.filesBase(spaceId)}`;
+        const res = await this.fetchFn(url, this.jsonRequest("GET"));
+        const data = await parseOrThrow$1(res, "listFiles");
+        return Array.isArray(data.files) ? data.files : [];
+    }
+    // -------------------------------------------------------------------------
+    filesBase(spaceId) {
+        return `${this.baseUrl}/api/spaces/${encodeURIComponent(spaceId)}/files`;
+    }
+    jsonRequest(method, body) {
+        const init = { method };
+        if (body !== undefined) {
+            init.headers = { "Content-Type": "application/json" };
+            init.body = JSON.stringify(body);
+        }
+        return init;
+    }
+}
+async function parseOrThrow$1(response, op) {
+    let parsed = null;
+    try {
+        parsed = await response.json();
+    }
+    catch {
+        // non-JSON body
+    }
+    if (!response.ok) {
+        const msg = parsed && typeof parsed === "object" && "error" in parsed
+            ? String(parsed.error)
+            : `${response.status} ${response.statusText}`;
+        throw new Error(`SharedSpaceClient.${op}: ${msg}`);
+    }
+    return parsed;
+}
+
+/**
+ * `client.storage` — file storage. Hides the `FileStorage` / `ShardClient` /
+ * `SharedSpaceClient` primitives behind the unified client.
+ *
+ *   const { stat, manifest } = await client.storage.writeFile({ spaceId, data, metadata })
+ *   const { data }          = await client.storage.readFile(spaceId, fileId)
+ *   const files             = await client.storage.listFiles()          // my shared files
+ *   const files             = await client.storage.listFiles({ spaceId }) // a space's files
+ *   await client.storage.deleteFile(spaceId, fileId)
+ *
+ * Model:
+ *   - **Files are written to a SharedSpace** (never the personal space). A file
+ *     is its manifest (per-chunk keys + global shard hashes); the manifest lives
+ *     in the space's gated, metered `/files` store, the shard ciphertext in the
+ *     global open `/api/shards` store.
+ *   - **The manifest is the capability** — anyone holding it reads the file from
+ *     the global shards, anywhere ({@link readByManifest}). Share a file by
+ *     sharing its manifest.
+ *   - **Personal discovery mirror** — on a successful write the SDK also records
+ *     the manifest in the user's `client.kv` under a reserved collection, so
+ *     {@link listFiles} (no `spaceId`) can show "files I've shared" without
+ *     enumerating spaces. The mirror is unmetered and is NOT a write path.
+ *
+ * For small structured values use `client.kv` instead.
+ */
+/** Reserved `client.kv` collection holding the personal manifest mirror. */
+const MIRROR_COLLECTION = "__files__";
+class StorageNamespace {
+    deps;
+    fileStorage = null;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * Write a file to a SharedSpace: shard ciphertext → the global store, the
+     * manifest → the space's gated store, and a mirror copy → the caller's
+     * personal index. Returns the `stat` and the `manifest` (share the manifest
+     * to let others read the file).
+     */
+    async writeFile(input) {
+        if (!input?.spaceId) {
+            throw new Error("client.storage.writeFile: `spaceId` is required (files live in a SharedSpace).");
+        }
+        const fs = this.fs();
+        const { manifest, stat } = await fs.writeFileToShards({
+            data: input.data,
+            metadata: input.metadata,
+        });
+        // Authoritative, metered write: the manifest into the space's gated store.
+        await this.space().writeFileManifest(input.spaceId, manifest);
+        // Best-effort personal discovery mirror (unmetered). A failure here
+        // leaves the file intact in the space — log and continue.
+        try {
+            await this.deps.kv.set(MIRROR_COLLECTION, manifest.id, {
+                spaceId: input.spaceId,
+                manifest,
+            });
+        }
+        catch (err) {
+            console.warn("client.storage.writeFile: discovery mirror failed (file still written):", err);
+        }
+        return { stat, manifest };
+    }
+    /** Read a file from its space (resolves the manifest, then the shards). */
+    async readFile(spaceId, fileId) {
+        return this.fs().readFile(spaceId, fileId);
+    }
+    /**
+     * Read a file straight from a manifest — the capability path. No space
+     * membership needed; this is how a shared file is opened.
+     */
+    async readByManifest(manifest) {
+        return this.fs().readFileFromShards(manifest);
+    }
+    /**
+     * List files. With no argument, returns the caller's own shared files from
+     * the personal mirror; with `{ spaceId }`, lists that space's files.
+     */
+    async listFiles(opts) {
+        if (opts?.spaceId)
+            return this.space().listFiles(opts.spaceId);
+        const ids = await this.deps.kv.list(MIRROR_COLLECTION);
+        const entries = await Promise.all(ids.map((id) => this.deps.kv.get(MIRROR_COLLECTION, id)));
+        return entries
+            .filter((e) => Boolean(e?.manifest))
+            .map((e) => manifestToStat(e.manifest));
+    }
+    /** Delete a file from its space and remove the personal mirror entry. */
+    async deleteFile(spaceId, fileId) {
+        const existed = await this.fs().deleteFile(spaceId, fileId);
+        try {
+            await this.deps.kv.delete(MIRROR_COLLECTION, fileId);
+        }
+        catch {
+            // mirror cleanup is best-effort
+        }
+        return existed;
+    }
+    /** Read a manifest verbatim (e.g. to share a file). */
+    async getManifest(spaceId, fileId) {
+        return this.fs().readManifest(spaceId, fileId);
+    }
+    // -------------------------------------------------------------------------
+    // Internals — lazily built so an unauthenticated client is cheap to create.
+    // -------------------------------------------------------------------------
+    fs() {
+        if (!this.fileStorage) {
+            this.fileStorage = new FileStorage({
+                shards: this.shards(),
+                space: this.space(),
+                rsWasmModule: this.deps.rsWasmModule,
+            });
+        }
+        return this.fileStorage;
+    }
+    _shards = null;
+    shards() {
+        // Global, content-addressed shard store. The credential-stamping fetch
+        // attaches the app key so PUTs are attributed + quota-gated; GETs are open.
+        if (!this._shards) {
+            this._shards = new ShardClient({
+                baseUrl: this.deps.baseUrl,
+                pathPrefix: "/api/shards",
+                fetch: this.deps.http.fetch,
+            });
+        }
+        return this._shards;
+    }
+    _space = null;
+    space() {
+        if (!this._space) {
+            this._space = new SharedSpaceClient({
+                baseUrl: this.deps.baseUrl,
+                fetch: this.deps.http.fetch,
+            });
+        }
+        return this._space;
+    }
+}
+
+/**
+ * An end-to-end-encrypted communication session for one local identity
+ * (`myId`) talking to an arbitrary set of peers. Wraps `KeyStore` +
+ * per-pair `DoubleRatchet` instances and owns the protocol bookkeeping
+ * (handshake reciprocation, dedup, role assignment, broadcast fan-out,
+ * recipient filtering) so application code doesn't have to.
+ *
+ * Transport-agnostic by design: the Session never touches a WebSocket
+ * (or HTTP, or anything else). Application code:
+ *   - calls `session.encrypt(text)` and gets back an array of frames it
+ *     ships over whatever transport it has;
+ *   - calls `session.receive(frame)` with each inbound frame and acts on
+ *     the typed result (plaintext, handshake-done, ignored).
+ *
+ * Frames are plain JSON objects with the same shape the existing chat
+ * protocol uses (`{ keyExchange: {...} }` and `{ cipherMessage: {...} }`),
+ * so this can drop into a chat app without changing the wire format.
+ */
+// ---------------------------------------------------------------------------
+// EncryptedSession
+// ---------------------------------------------------------------------------
+class EncryptedSession {
+    myId;
+    keyStore;
+    /** One DoubleRatchet per peer pair. */
+    ratchets = new Map();
+    /** Peers we've already sent our keyExchange to in this Session. */
+    sentHandshakeTo = new Set();
+    /** Resolved when own keys are generated and ready to use. */
+    _ready;
+    _resolveReady;
+    _initialized = false;
+    constructor(opts) {
+        if (!opts || !opts.myId) {
+            throw new Error("EncryptedSession: `myId` is required");
+        }
+        this.myId = opts.myId;
+        this.keyStore = KeyStore.getInstance();
+        this._ready = new Promise((resolve) => {
+            this._resolveReady = resolve;
+        });
+    }
+    /** A promise that resolves once `initialize()` has completed. */
+    get ready() {
+        return this._ready;
+    }
+    /** Our local identifier. */
+    get id() {
+        return this.myId;
+    }
+    /**
+     * Generate this client's ECDH + ECDSA keypair (idempotent — safe to call
+     * multiple times across reconnects; only the first call generates).
+     */
+    async initialize() {
+        if (this._initialized)
+            return;
+        if (!this.keyStore.getKeyPair(this.myId)) {
+            await this.keyStore.generateOwnKeyPair(this.myId);
+        }
+        this._initialized = true;
+        this._resolveReady();
+    }
+    /**
+     * Build the keyExchange frame this client should send to peers when it
+     * comes online. Application is responsible for actually transmitting it
+     * (e.g. ws.send(JSON.stringify(frame))).
+     */
+    async getOwnKeyExchange() {
+        await this._ready;
+        const ownEcdh = this.keyStore.getKeyPair(this.myId);
+        const ownEcdsa = this.keyStore.getAuthKeyPair(this.myId);
+        if (!ownEcdh || !ownEcdsa) {
+            throw new Error("EncryptedSession.getOwnKeyExchange: keys not initialized");
+        }
+        return {
+            keyExchange: {
+                type: "handshake",
+                userId: this.myId,
+                ecdhPublicKey: await exportJwkBase64(ownEcdh.publicKey),
+                ecdsaPublicKey: await exportJwkBase64(ownEcdsa.publicKey),
+            },
+        };
+    }
+    /**
+     * Encrypt a plaintext to every peer we currently have a ratchet for, and
+     * return one cipherMessage frame per recipient. The application sends
+     * each frame over its transport.
+     *
+     * If there are no peers yet (or all peers are still mid-handshake), the
+     * returned array may be empty — the caller should typically render the
+     * outgoing message locally in that case (since there's no one to send
+     * it to yet).
+     */
+    async encrypt(plaintext) {
+        await this._ready;
+        const frames = [];
+        for (const peerId of this.ratchets.keys()) {
+            const ratchet = this.ratchets.get(peerId);
+            const sessionId = this._sessionIdFor(peerId);
+            const cipherMessage = await ratchet.encrypt(plaintext, 
+            /* newDhKey */ false, this.myId, peerId, sessionId, "specific");
+            frames.push({ cipherMessage });
+        }
+        return frames;
+    }
+    /**
+     * Hand an inbound frame to the session. Returns a typed result the
+     * application acts on.
+     *
+     *   - `kind: 'plaintext'`         — decrypted; render `result.text`
+     *   - `kind: 'handshake'`         — a peer's keys are now stored, and if
+     *                                   `result.outbound` is set, send it
+     *   - `kind: 'ignored'`           — not for us, malformed, duplicate, etc.
+     *
+     * Calling code should always handle `'ignored'` (no UI side effect).
+     */
+    async receive(frame) {
+        await this._ready;
+        // -- handshake frame -----------------------------------------------------
+        if (isKeyExchangeFrame(frame)) {
+            const kx = frame.keyExchange;
+            const peerId = kx.userId;
+            if (peerId === this.myId) {
+                return { kind: "ignored", reason: "own keyExchange echo" };
+            }
+            const isNew = !this.ratchets.has(peerId);
+            // (Re-)store the peer's pubkeys + (re-)build the ratchet if needed.
+            const peerEcdh = await importJwkBase64(kx.ecdhPublicKey, "ECDH");
+            const peerEcdsa = await importJwkBase64(kx.ecdsaPublicKey, "ECDSA");
+            await this.keyStore.storeRemotePublicKeys(peerId, peerEcdh, peerEcdsa);
+            if (isNew) {
+                const isClient = this.myId < peerId;
+                const ratchet = new DoubleRatchet(this.myId, peerId, "specific", isClient);
+                await ratchet.initializeSession(isClient);
+                this.ratchets.set(peerId, ratchet);
+            }
+            // Reciprocate exactly once per peer per session lifetime.
+            let outbound = null;
+            if (isNew && !this.sentHandshakeTo.has(peerId)) {
+                outbound = await this.getOwnKeyExchange();
+                this.sentHandshakeTo.add(peerId);
+            }
+            return { kind: "handshake", peerId, outbound };
+        }
+        // -- ciphertext frame ----------------------------------------------------
+        if (isCipherFrame(frame)) {
+            const cipherMessage = frame.cipherMessage;
+            const header = cipherMessage?.header;
+            if (!header) {
+                return { kind: "ignored", reason: "cipherMessage has no header" };
+            }
+            if (header.senderId === this.myId) {
+                return { kind: "ignored", reason: "own outbound echo" };
+            }
+            if (header.recipientId && header.recipientId !== this.myId) {
+                return { kind: "ignored", reason: "addressed to a different peer" };
+            }
+            const ratchet = this.ratchets.get(header.senderId);
+            if (!ratchet) {
+                return {
+                    kind: "ignored",
+                    reason: `no ratchet with sender ${header.senderId} (handshake hasn't completed)`,
+                };
+            }
+            const isClient = this.myId < header.senderId;
+            let text;
+            try {
+                text = await ratchet.decrypt(cipherMessage, isClient);
+            }
+            catch (err) {
+                // DoubleRatchet's wallclock-based replay-protection check throws
+                // "CipherMessage too old, possible replay attack" for any frame
+                // older than 5 minutes. Real replays still fail downstream because
+                // the message key has been consumed; the wallclock check is a
+                // defense-in-depth heuristic, not a security boundary. Treating it
+                // as `ignored` lets the channel survive legacy backlog replays and
+                // CF WS-idle-timeout reconnect cycles without spamming the
+                // channel's ERROR stream.
+                const msg = err instanceof Error ? err.message : String(err);
+                if (msg.includes("too old") || msg.includes("replay attack")) {
+                    return { kind: "ignored", reason: `stale cipherMessage rejected: ${msg}` };
+                }
+                throw err;
+            }
+            return { kind: "plaintext", from: header.senderId, text, cipherMessage };
+        }
+        return { kind: "ignored", reason: "unknown frame type" };
+    }
+    // -- introspection ---------------------------------------------------------
+    /** List of peer ids we have an established ratchet for. */
+    peers() {
+        return Array.from(this.ratchets.keys());
+    }
+    /** Has the handshake completed for this peer? */
+    hasRatchetFor(peerId) {
+        return this.ratchets.has(peerId);
+    }
+    /**
+     * Tear down a peer's ratchet (e.g. when they leave the room). The peer's
+     * stored keys remain in `KeyStore` so a fresh handshake can be set up
+     * later without re-fetching them, but the ratchet state is dropped.
+     */
+    forgetPeer(peerId) {
+        this.ratchets.delete(peerId);
+        this.sentHandshakeTo.delete(peerId);
+    }
+    // -- internals -------------------------------------------------------------
+    /** Deterministic per-pair session id — same string on both sides. */
+    _sessionIdFor(peerId) {
+        return [this.myId, peerId].sort().join(":");
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers — JWK <-> base64 string for key transport
+// ---------------------------------------------------------------------------
+async function exportJwkBase64(key) {
+    const jwk = await crypto.subtle.exportKey("jwk", key);
+    return btoa(JSON.stringify(jwk));
+}
+async function importJwkBase64(b64, type) {
+    const jwk = JSON.parse(atob(b64));
+    const algorithm = type === "ECDH"
+        ? { name: "ECDH", namedCurve: "P-384" }
+        : { name: "ECDSA", namedCurve: "P-384" };
+    const usages = type === "ECDH" ? [] : ["verify"];
+    return await crypto.subtle.importKey("jwk", jwk, algorithm, true, usages);
+}
+// ---------------------------------------------------------------------------
+// Type guards
+// ---------------------------------------------------------------------------
+function isKeyExchangeFrame(frame) {
+    const kx = frame.keyExchange;
+    if (!kx || typeof kx !== "object")
+        return false;
+    const k = kx;
+    return (typeof k.userId === "string" &&
+        typeof k.ecdhPublicKey === "string" &&
+        typeof k.ecdsaPublicKey === "string");
+}
+function isCipherFrame(frame) {
+    const cm = frame.cipherMessage;
+    if (!cm || typeof cm !== "object")
+        return false;
+    const m = cm;
+    return Boolean(m.header && m.ciphertext && m.nonce);
+}
+
+/**
+ * BroadcastChannel — a turnkey end-to-end encrypted channel for multi-peer
+ * "room"-style apps (e.g. a chat). Wires together:
+ *
+ *   - `WSTransport` for socket lifecycle, reconnect, and offline frame queue
+ *   - `EncryptedSession` for per-peer Double Ratchet state, handshake
+ *     reciprocation, fan-out encryption, and recipient filtering
+ *
+ * The host app only deals with high-level events and method calls; it never
+ * touches `new WebSocket(...)` or builds cipherMessage frames by hand.
+ *
+ * Wire protocol (kept compatible with the existing chat protocol so this
+ * drops into the deployed Accelerator without server changes):
+ *
+ *   outbound: `{ keyExchange: {...} }`      — produced by us on `announce()`
+ *             `{ cipherMessage: {...} }`    — produced by `send(text)`,
+ *                                              one frame per peer
+ *             arbitrary JSON                — sent via `sendRaw(obj)`
+ *
+ *   inbound:  `{ keyExchange: {...} }`      — routed into EncryptedSession;
+ *                                              emits `peer_handshake`
+ *             `{ cipherMessage: {...} }`    — decrypted; emits `message`
+ *             anything else                 — passes through as `raw_frame`
+ *                                              (the app decides what to do)
+ *
+ * **Event scoping.** Unlike `Network`, BroadcastChannel uses a per-instance
+ * `EventTarget`, so two channels (e.g. two rooms in the same app) don't
+ * cross-contaminate each other's events.
+ *
+ * Note: this class shadows the `BroadcastChannel` Web API global (cross-tab
+ * messaging) only when imported by name. They're unrelated.
+ */
+// ---------------------------------------------------------------------------
+// Event names
+// ---------------------------------------------------------------------------
+/**
+ * Event names BroadcastChannel emits. Lifecycle events reuse the
+ * `EventCoreEvents` string values (`connected`, `disconnected`, etc.) so
+ * apps can use shared constants if they want. Channel-specific events are
+ * prefixed `channel:` to avoid colliding with other event systems in the
+ * same app.
+ */
+const BroadcastChannelEvents = {
+    CONNECTED: EventCoreEvents.CONNECTED,
+    DISCONNECTED: EventCoreEvents.DISCONNECTED,
+    RECONNECTING: EventCoreEvents.RECONNECTING,
+    ERROR: EventCoreEvents.ERROR,
+    /** A peer's ratchet is now ready. `detail.peerId` is the peer's id. */
+    PEER_HANDSHAKE: "channel:peer_handshake",
+    /** Decrypted message. `detail` is `{ from, text, cipherMessage }`. */
+    MESSAGE: "channel:message",
+    /** Inbound frame BroadcastChannel didn't recognize. App handles it. */
+    RAW_FRAME: "channel:raw_frame",
+};
+// ---------------------------------------------------------------------------
+// BroadcastChannel
+// ---------------------------------------------------------------------------
+class BroadcastChannel {
+    transport;
+    session;
+    myId;
+    autoAnnounce;
+    announced = false;
+    /** Per-instance EventTarget — events do NOT leak across BroadcastChannels. */
+    events = new EventTarget();
+    constructor(opts) {
+        if (!opts || !opts.myId) {
+            throw new Error("BroadcastChannel: `myId` is required");
+        }
+        this.myId = opts.myId;
+        this.autoAnnounce = opts.autoAnnounce ?? false;
+        this.transport = new WSTransport(opts);
+        this.session = new EncryptedSession({ myId: opts.myId });
+        // Pass-through lifecycle events from the transport. `EventCore.on` is
+        // static so it routes back through the shared singleton; we bridge it
+        // into our instance-scoped event target.
+        this.transport.on(EventCoreEvents.CONNECTED, () => {
+            // Reset the announce flag on every (re)connect. CF Workers WebSockets
+            // hit an idle timeout and force reconnects; without resetting, the
+            // SDK would short-circuit announce() and any peer who joined the
+            // room after our last announce would never see our pubkey.
+            this.announced = false;
+            this.emit(BroadcastChannelEvents.CONNECTED);
+            if (this.autoAnnounce) {
+                void this.announce();
+            }
+        });
+        this.transport.on(EventCoreEvents.DISCONNECTED, () => {
+            this.emit(BroadcastChannelEvents.DISCONNECTED);
+        });
+        this.transport.on(EventCoreEvents.RECONNECTING, (e) => {
+            this.emit(BroadcastChannelEvents.RECONNECTING, e.detail);
+        });
+        this.transport.on(EventCoreEvents.ERROR, (e) => {
+            this.emit(BroadcastChannelEvents.ERROR, e.detail);
+        });
+        // Route inbound raw frames through our framing/decryption logic.
+        this.transport.on(EventCoreEvents.MESSAGE, (e) => {
+            void this.handleInboundFrame(e.detail);
+        });
+    }
+    // -- event API -------------------------------------------------------------
+    /** Subscribe to a channel event. Handler receives a CustomEvent. */
+    on(event, handler) {
+        this.events.addEventListener(event, handler);
+    }
+    /** Unsubscribe. */
+    off(event, handler) {
+        this.events.removeEventListener(event, handler);
+    }
+    emit(event, detail) {
+        this.events.dispatchEvent(new CustomEvent(event, { detail }));
+    }
+    // -- lifecycle -------------------------------------------------------------
+    /** Generate our keys (idempotent) and open the WebSocket. */
+    async connect() {
+        await this.session.initialize();
+        await this.transport.connect();
+    }
+    /** Close the WebSocket and stop reconnecting. */
+    disconnect() {
+        this.transport.disconnect();
+    }
+    /**
+     * Send our `keyExchange` frame to the room. Idempotent — only sends on the
+     * first call. Call this once your higher-level handshake (e.g. sending a
+     * `{name}` identification frame) has completed.
+     */
+    async announce() {
+        if (this.announced)
+            return;
+        this.announced = true;
+        const frame = await this.session.getOwnKeyExchange();
+        this.transport.send(JSON.stringify(frame));
+    }
+    /**
+     * Encrypt `plaintext` to every peer we have a ratchet with, and send each
+     * cipherMessage as its own WS frame. Returns the number of peers we sent to
+     * (0 if no peers are handshaken yet — in which case the caller should
+     * typically render the message locally for the sender and try again later).
+     */
+    async send(plaintext) {
+        const frames = await this.session.encrypt(plaintext);
+        for (const frame of frames) {
+            this.transport.send(JSON.stringify(frame));
+        }
+        return frames.length;
+    }
+    /**
+     * Send an arbitrary JSON-serializable frame as-is. The app uses this for
+     * any frame that isn't channel-managed (e.g. a chat's `{name}`, `{file}`,
+     * or unencrypted `{message}`).
+     */
+    sendRaw(frame) {
+        this.transport.send(JSON.stringify(frame));
+    }
+    // -- introspection ---------------------------------------------------------
+    /** List of peer ids we have an established ratchet for. */
+    peers() {
+        return this.session.peers();
+    }
+    /** Drop a peer's ratchet (e.g. when they leave the room). */
+    forgetPeer(peerId) {
+        this.session.forgetPeer(peerId);
+    }
+    isConnected() {
+        return this.transport.isConnected();
+    }
+    // -- internals -------------------------------------------------------------
+    async handleInboundFrame(raw) {
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (err) {
+            this.emit(BroadcastChannelEvents.ERROR, err);
+            return;
+        }
+        if (!parsed || typeof parsed !== "object") {
+            this.emit(BroadcastChannelEvents.RAW_FRAME, parsed);
+            return;
+        }
+        const obj = parsed;
+        // Channel-managed: keyExchange & cipherMessage. Anything else is RAW_FRAME.
+        if ("keyExchange" in obj || "cipherMessage" in obj) {
+            try {
+                const result = await this.session.receive(obj);
+                if (result.kind === "handshake") {
+                    if (result.outbound) {
+                        this.transport.send(JSON.stringify(result.outbound));
+                    }
+                    this.emit(BroadcastChannelEvents.PEER_HANDSHAKE, { peerId: result.peerId });
+                }
+                else if (result.kind === "plaintext") {
+                    this.emit(BroadcastChannelEvents.MESSAGE, {
+                        from: result.from,
+                        text: result.text,
+                        cipherMessage: result.cipherMessage,
+                    });
+                }
+                // `ignored` is intentionally swallowed; subscribe to ERROR for bad frames.
+            }
+            catch (err) {
+                this.emit(BroadcastChannelEvents.ERROR, err);
+            }
+            return;
+        }
+        this.emit(BroadcastChannelEvents.RAW_FRAME, obj);
     }
 }
-/** Normalize `data` to a flat `Uint8Array`. */
-async function toUint8Array(data) {
-    if (data instanceof Uint8Array)
-        return data;
-    // Blob covers File too (File extends Blob in every runtime we target).
-    const ab = await data.arrayBuffer();
-    return new Uint8Array(ab);
-}
 
 /**
  * SpaceCipher — pure crypto for the fan-out group-encryption layer.
@@ -4987,12 +5415,27 @@ class Space {
     /** Open the space websocket (resolves the ticket + identity lazily). */
     async connect() {
         if (!this.channel) {
-            const ticket = await this.deps.fetchTicket();
-            const url = `${this.deps.wsBaseUrl}/api/spaces/${encodeURIComponent(this.name)}/websocket` +
-                (ticket ? `?ticket=${encodeURIComponent(ticket)}` : "");
+            // The WS upgrade ticket is single-use + short-TTL, so a reconnect
+            // must mint a FRESH one — otherwise the socket drops (idle timeout,
+            // network blip) and never comes back. `buildUrl` is handed to the
+            // transport as a `urlProvider` it calls before each reconnect.
+            const buildUrl = async () => {
+                const ticket = await this.deps.fetchTicket();
+                return (`${this.deps.wsBaseUrl}/api/spaces/${encodeURIComponent(this.name)}/websocket` +
+                    (ticket ? `?ticket=${encodeURIComponent(ticket)}` : ""));
+            };
+            const url = await buildUrl();
             this.channel = this.deps.createChannel
                 ? this.deps.createChannel(url, this.deps.myId())
-                : new BroadcastChannel({ url, myId: this.deps.myId(), autoAnnounce: false });
+                : new BroadcastChannel({
+                    url,
+                    myId: this.deps.myId(),
+                    autoAnnounce: false,
+                    urlProvider: buildUrl,
+                    // Keep recovering across network flaps (each attempt mints a
+                    // fresh ticket); teardown calls disconnect() which stops it.
+                    maxReconnectAttempts: 0,
+                });
             for (const [event, handler] of this.pending)
                 this.channel.on(event, handler);
             this.pending.length = 0;
@@ -5056,23 +5499,7 @@ class Space {
      * persisted `spaceMessage`. Requires a keyring.
      */
     async sendMessage(payload, opts = {}) {
-        const cipher = this.requireCipher(opts.contentType);
-        const message = new Message(payload);
-        const headers = await cipher.seal(message.serialize());
-        const source = this.deps.myId();
-        const subject = opts.channel ?? "default";
-        // Sign the message with our identity ECDSA key so receivers can verify
-        // authorship end-to-end (independent of the relay's `source` stamp).
-        const authPriv = KeyStore.getInstance().getAuthKeyPair(source)?.privateKey;
-        if (authPriv) {
-            const canonical = canonicalMessage({
-                source, target: this.name, subject,
-                epoch: Number(headers.epoch), iv: String(headers.iv), ciphertext: String(headers.ciphertext),
-            });
-            headers.sig = await signSpaceMessage(canonical, authPriv);
-        }
-        const packet = new Packet({ subject, source, target: this.name, headers });
-        this.sendRaw({ spaceMessage: packet.serialize() });
+        this.sendRaw({ spaceMessage: await this.sealMessage(payload, opts.channel, opts.contentType) });
     }
     /** Subscribe to decrypted fan-out messages. Returns an unsubscribe fn. */
     onMessage(handler) {
@@ -5080,6 +5507,56 @@ class Space {
         this.events.addEventListener("message", listener);
         return () => this.events.removeEventListener("message", listener);
     }
+    /**
+     * Edit a persisted message IN PLACE, addressed by its server
+     * {@link SpaceMessageEvent.handle}. Re-seals `payload` and asks the server
+     * to replace the stored entry; the server authorizes against the original
+     * author. Receivers get an {@link onMessageEdited} event carrying the new
+     * content at the same handle. This is a generic persisted-item edit — the
+     * server has no notion of what the payload means.
+     */
+    async editMessage(handle, payload, opts = {}) {
+        const spaceMessage = await this.sealMessage(payload, opts.channel, opts.contentType);
+        this.sendRaw({ editSpaceMessage: { ts: handle, spaceMessage } });
+    }
+    /**
+     * Hard-delete a persisted message by its server {@link SpaceMessageEvent.handle}
+     * — the ciphertext is removed from storage. Server authorizes against the
+     * original author. Receivers get an {@link onMessageDeleted} event.
+     */
+    async deleteMessage(handle) {
+        this.sendRaw({ deleteSpaceMessage: { ts: handle } });
+    }
+    /** Subscribe to in-place edits of persisted messages (new content at the same handle). */
+    onMessageEdited(handler) {
+        const listener = (e) => handler(e.detail);
+        this.events.addEventListener("message-edited", listener);
+        return () => this.events.removeEventListener("message-edited", listener);
+    }
+    /** Subscribe to deletions of persisted messages. */
+    onMessageDeleted(handler) {
+        const listener = (e) => handler(e.detail);
+        this.events.addEventListener("message-deleted", listener);
+        return () => this.events.removeEventListener("message-deleted", listener);
+    }
+    /**
+     * Broadcast an ephemeral, never-persisted signal to the room over the
+     * generic `pub` relay. `subject` is an app-defined routing key; `data` is
+     * opaque. The transport stays domain-agnostic — app concepts like typing
+     * indicators, presence, or live cursors are built on top of this. No-op if
+     * the space isn't connected (ephemeral signals aren't worth queuing).
+     */
+    sendEphemeral(subject, data) {
+        if (!this.isConnected())
+            return;
+        this.sendRaw({ pub: { subject, data } });
+    }
+    /** Subscribe to inbound ephemeral signals. `from` is the authenticated sender. */
+    onEphemeral(handler) {
+        const listener = (e) => handler(e.detail);
+        this.events.addEventListener("ephemeral", listener);
+        return () => this.events.removeEventListener("ephemeral", listener);
+    }
     /** Subscribe to inbound join requests (for a key-holder to admit). */
     onJoinRequest(handler) {
         const listener = (e) => handler(e.detail);
@@ -5162,16 +5639,20 @@ class Space {
         return this.requireKeyring().rotate(roster);
     }
     // -- room-scoped files (no websocket needed) -------------------------------
-    async putFile(file, metadata) {
-        return this.fileStorage().writeFileToShards({ data: file, metadata });
+    async putFile(file, metadata, opts = {}) {
+        return this.fileStorage().writeFileToShards({ data: file, metadata, onProgress: opts.onProgress });
     }
     async getFile(manifest) {
         return this.fileStorage().readFileFromShards(manifest);
     }
     fileStorage() {
+        // Global, content-addressed shard store — same store `client.storage`
+        // uses, so a file shared into a channel resolves from anywhere by
+        // manifest. (Shards are encrypted ciphertext; the manifest is the
+        // capability.)
         const shards = new ShardClient({
             baseUrl: this.deps.httpBaseUrl,
-            pathPrefix: `/api/spaces/${encodeURIComponent(this.name)}/shards`,
+            pathPrefix: "/api/shards",
             fetch: this.deps.fetch,
         });
         return new FileStorage({ shards });
@@ -5191,11 +5672,39 @@ class Space {
         if (!f || typeof f !== "object")
             return;
         if (typeof f.spaceMessage === "string" && this.cipher) {
-            const decoded = await this.decodeFrame(f.spaceMessage, this.cipher, /*raw*/ true);
+            const decoded = await this.decodeFrame(f.spaceMessage, this.cipher, /*raw*/ true, Number(f.timestamp ?? 0));
             if (decoded)
                 this.emitEvent("message", decoded);
             return;
         }
+        if (f.editSpaceMessage && typeof f.editSpaceMessage === "object" && this.cipher) {
+            // Server-authoritative in-place edit: new sealed content at the same
+            // handle. Decode and surface it; the app replaces by `handle`.
+            const e = f.editSpaceMessage;
+            if (typeof e.spaceMessage === "string") {
+                const decoded = await this.decodeFrame(e.spaceMessage, this.cipher, /*raw*/ true, Number(e.ts ?? 0));
+                if (decoded)
+                    this.emitEvent("message-edited", decoded);
+            }
+            return;
+        }
+        if (f.deleteSpaceMessage && typeof f.deleteSpaceMessage === "object") {
+            const d = f.deleteSpaceMessage;
+            this.emitEvent("message-deleted", { handle: Number(d.ts ?? 0) });
+            return;
+        }
+        if (f.pub && typeof f.pub === "object") {
+            // Generic ephemeral relay frame. The server stamps the authenticated
+            // sender as `name`; `pub` carries the app's {subject, data}. We
+            // surface the authenticated `name` as `from` (not any client-set
+            // value inside `pub`), so app signals can't spoof their sender.
+            const p = f.pub;
+            const from = typeof f.name === "string" ? f.name : "";
+            if (from && typeof p.subject === "string") {
+                this.emitEvent("ephemeral", { from, subject: p.subject, data: p.data });
+            }
+            return;
+        }
         if (f.joinRequest && typeof f.joinRequest === "object") {
             const req = f.joinRequest;
             this.emitEvent("join-request", req);
@@ -5212,19 +5721,46 @@ class Space {
             void this.deps.keyring.pullKeys().catch(() => { });
         }
     }
+    /**
+     * Seal `payload` once with the current group key + sign it, returning the
+     * serialized `Packet` string. Shared by send (a new message) and edit
+     * (replacement content for an existing handle). Requires a keyring.
+     */
+    async sealMessage(payload, channel, contentType) {
+        const cipher = this.requireCipher(contentType);
+        const message = new Message(payload);
+        const headers = await cipher.seal(message.serialize());
+        const source = this.deps.myId();
+        const subject = channel ?? "default";
+        // Sign with our identity ECDSA key so receivers can verify authorship
+        // end-to-end (independent of the relay's `source` stamp).
+        const authPriv = KeyStore.getInstance().getAuthKeyPair(source)?.privateKey;
+        if (authPriv) {
+            const canonical = canonicalMessage({
+                source, target: this.name, subject,
+                epoch: Number(headers.epoch), iv: String(headers.iv), ciphertext: String(headers.ciphertext),
+            });
+            headers.sig = await signSpaceMessage(canonical, authPriv);
+        }
+        return new Packet({ subject, source, target: this.name, headers }).serialize();
+    }
     /**
      * Decode one persisted/broadcast frame into a SpaceMessageEvent.
      * `isRawFrame` true means `input` is the already-extracted `spaceMessage`
-     * packet string; false means it's the full `{spaceMessage, name, ...}` frame.
+     * packet string (and `serverTs` carries the message's storage handle from
+     * the enclosing frame); false means `input` is the full
+     * `{spaceMessage, name, timestamp}` frame and the handle is read from it.
      */
-    async decodeFrame(input, cipher, isRawFrame = false) {
+    async decodeFrame(input, cipher, isRawFrame = false, serverTs = 0) {
         try {
             let packetJson = input;
+            let handle = serverTs;
             if (!isRawFrame) {
                 const outer = JSON.parse(input);
                 if (typeof outer.spaceMessage !== "string")
                     return null;
                 packetJson = outer.spaceMessage;
+                handle = Number(outer.timestamp ?? 0);
             }
             const packet = Packet.deserialize(packetJson);
             if (!cipher.handles(packet.headers))
@@ -5245,6 +5781,7 @@ class Space {
                 channel: packet.subject,
                 epoch: Number(packet.headers?.epoch ?? 0),
                 contentType: packet.headers?.contentType,
+                handle,
                 message,
             };
         }
@@ -5260,6 +5797,12 @@ class Space {
      * nothing to verify against → reject.
      */
     async verifySender(packet) {
+        // Trust our OWN messages — we sent them, so there's nothing to prove
+        // against the roster. This also keeps a returning member (who loaded a
+        // cached key and never re-published a join-request) from dropping the
+        // echo of their own messages when their `ecdsaPub` isn't in the roster.
+        if (packet.source === this.deps.myId())
+            return true;
         const keyring = this.deps.keyring;
         const sig = packet.headers?.sig;
         if (!keyring || typeof sig !== "string")
@@ -5756,6 +6299,34 @@ class KeyringClient {
     async invite(username) {
         await this.post("/keyring/invite", { username });
     }
+    // -- Shareable invite links ----------------------------------------------
+    // A capability token tied to this space. Redeeming it allowlists the holder
+    // so the keeper admits them — the link IS the invitation. Mint/list/revoke
+    // require the caller to be the creator or an existing member.
+    async createInviteLink(opts = {}) {
+        return this.post("/keyring/link", opts);
+    }
+    async listInviteLinks() {
+        const body = await this.get("/keyring/links");
+        return body.links ?? [];
+    }
+    /** Set a member's role ("viewer" | "editor"). Owner-only on the server. */
+    async setMemberRole(username, role) {
+        await this.post("/keyring/role", { username, role });
+    }
+    /** Roster with roles (owner/members only). */
+    async members() {
+        const body = await this.get("/keyring/members");
+        return body.members ?? [];
+    }
+    async revokeInviteLink(token) {
+        await this.post("/keyring/link-revoke", { token });
+    }
+    /** Redeem a link: the server allowlists this member and asks the keeper to
+     *  wrap the group key for their identity. Caller must be authenticated. */
+    async redeemInvite(req) {
+        await this.post("/keyring/redeem", req);
+    }
     async fetchMetadata() {
         try {
             return await this.get("/metadata");
@@ -5893,6 +6464,56 @@ class SpaceNamespace {
         return this.joinSpace(spaceId, opts);
     }
     // -------------------------------------------------------------------------
+    // Invite links — shareable, keeper-gated invitations to a space. The token
+    // is a capability: anyone signed in who redeems it is admitted by the
+    // keeper. Mint/list/revoke require the caller to be the space's creator or
+    // an existing member.
+    // -------------------------------------------------------------------------
+    /** Mint a shareable invite link for a space. `opts.expiresInSec` / `maxUses`
+     *  bound it (0/undefined = unlimited); `opts.role` ("viewer"|"editor") is the
+     *  access granted to redeemers (default viewer). Returns the link. */
+    async createInviteLink(spaceId, opts = {}) {
+        return this.keyringFor(spaceId).createInviteLink(opts);
+    }
+    /** Set a member's role on a space ("viewer" | "editor"). Owner-only. */
+    async setMemberRole(spaceId, username, role) {
+        await this.keyringFor(spaceId).setMemberRole(username, role);
+    }
+    /** Roster with roles (owner/members only). */
+    async members(spaceId) {
+        return this.keyringFor(spaceId).members();
+    }
+    /** List a space's active invite links (creator/members only). */
+    async listInviteLinks(spaceId) {
+        return this.keyringFor(spaceId).listInviteLinks();
+    }
+    /** Revoke an invite link by token. */
+    async revokeInviteLink(spaceId, token) {
+        await this.keyringFor(spaceId).revokeInviteLink(token);
+    }
+    /**
+     * Join a space using an invite link: redeem the token (the keeper admits
+     * this member), then connect and resolve once the group key arrives.
+     * Returns the open {@link Space}.
+     */
+    async joinByInvite(spaceId, token, opts = {}) {
+        const memberId = this.myId();
+        const { ecdhPub, ecdsaPub } = await this.ensureIdentity(memberId);
+        await this.keyringFor(spaceId).redeemInvite({ token, identityEcdhPub: ecdhPub, identityEcdsaPub: ecdsaPub });
+        return this.joinSpace(spaceId, opts);
+    }
+    /** The current member roster of a space (member id → identity public keys). */
+    async roster(spaceId) {
+        return this.keyringFor(spaceId).fetchRoster();
+    }
+    keyringFor(spaceId) {
+        return new KeyringClient({
+            spaceId,
+            httpBaseUrl: this.deps.http.baseUrl,
+            fetch: this.deps.http.fetch,
+        });
+    }
+    // -------------------------------------------------------------------------
     // Internals
     // -------------------------------------------------------------------------
     async build(spaceId, historyPolicy) {
@@ -5959,6 +6580,133 @@ class SpaceNamespace {
     }
 }
 
+/**
+ * `client.agents` — manage an app's **Programmable Agents** (server-side
+ * "virtual users" backed by Workers AI).
+ *
+ *   const { config } = await client.agents.create(appId, {
+ *     handle: '@assistant', displayName: 'Assistant',
+ *     systemPrompt: 'You are a helpful teammate in this Space.',
+ *     triggers: [{ type: 'mention' }],
+ *   });
+ *   await client.agents.enable(appId, config.agentId, spaceId);  // per-Space opt-in
+ *
+ * These are MANAGEMENT calls — the agent itself runs on the accelerator. Only an
+ * app's owner or an editor of its shared Space may create/update/enable an agent
+ * (viewers can read). Authorization rides the user session token; non-owner
+ * editors pass their management Space via `opts.space`.
+ *
+ * v1 is "prompts + persona": a system prompt, a model, named prompt `skills`,
+ * and `triggers` that decide when the agent speaks. No tools, no code.
+ */
+class AgentsNamespace {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** List the app's agents. */
+    async list(appId, opts = {}) {
+        const res = await this.deps.http.get(this.path(appId, "", opts));
+        return res.agents ?? [];
+    }
+    /** Read one agent (config + identity keys). */
+    async get(appId, agentId, opts = {}) {
+        return this.deps.http.get(this.path(appId, `/${encodeURIComponent(agentId)}`, opts));
+    }
+    /** Create an agent (owner/editor only). */
+    async create(appId, input, opts = {}) {
+        return this.deps.http.post(this.path(appId, "", {}), { ...input, space: opts.space });
+    }
+    /** Update an agent's editor-settable fields (owner/editor only). */
+    async update(appId, agentId, patch, opts = {}) {
+        return this.deps.http.patch(this.path(appId, `/${encodeURIComponent(agentId)}`, {}), { ...patch, space: opts.space });
+    }
+    /** Delete an agent (owner/editor only). */
+    async delete(appId, agentId, opts = {}) {
+        return this.deps.http.del(this.path(appId, `/${encodeURIComponent(agentId)}`, {}), { space: opts.space });
+    }
+    /** Enable the agent on a Space (per-Space opt-in). */
+    async enable(appId, agentId, spaceId, opts = {}) {
+        return this.deps.http.post(this.path(appId, `/${encodeURIComponent(agentId)}/enable`, {}), { targetSpaceId: spaceId, space: opts.space });
+    }
+    /** Disable the agent on a Space. */
+    async disable(appId, agentId, spaceId, opts = {}) {
+        return this.deps.http.post(this.path(appId, `/${encodeURIComponent(agentId)}/disable`, {}), { targetSpaceId: spaceId, space: opts.space });
+    }
+    path(appId, suffix, opts) {
+        const q = opts.space ? `?space=${encodeURIComponent(opts.space)}` : "";
+        return `/api/apps/${encodeURIComponent(appId)}/agents${suffix}${q}`;
+    }
+}
+
+/**
+ * `client.functions` — manage an app's **serverless functions** (developer-
+ * authored code that runs on the accelerator).
+ *
+ *   const { config } = await client.functions.deploy(appId, {
+ *     name: 'hello', displayName: 'Hello',
+ *     code: `export default { fetch: () => new Response('hi') }`,
+ *     triggers: { http: { enabled: true } },
+ *   });
+ *   // HTTP-reachable at  hello--<slug>.fns.muhkoo.dev
+ *   await client.functions.enable(appId, config.functionId, spaceId); // Space-bound
+ *
+ * These are MANAGEMENT calls — the function itself runs on the accelerator
+ * (uploaded just-in-time, decrypted only at invocation). Only an app's owner or
+ * an editor of its shared Space may deploy/update/enable (viewers read).
+ * Authorization rides the user session token; non-owner editors pass their
+ * management Space via `opts.space`.
+ *
+ * v1 is "compute-only": a function is an untrusted single-module ES worker
+ * (`export default { fetch }`) with NO platform bindings — it reaches the
+ * platform as an external client (the end-user session is passed through). Two
+ * triggers: `http` (its own subdomain) and `space` (invoked on Space messages,
+ * like a Programmable Agent).
+ */
+class FunctionsNamespace {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** List the app's functions. */
+    async list(appId, opts = {}) {
+        const res = await this.deps.http.get(this.path(appId, "", opts));
+        return res.functions ?? [];
+    }
+    /** Read one function's config. */
+    async get(appId, functionId, opts = {}) {
+        return this.deps.http.get(this.path(appId, `/${encodeURIComponent(functionId)}`, opts));
+    }
+    /** Read a function's decrypted source (owner/editor; for the editor UI). */
+    async code(appId, functionId, opts = {}) {
+        return this.deps.http.get(this.path(appId, `/${encodeURIComponent(functionId)}/code`, opts));
+    }
+    /** Deploy (create) a function (owner/editor only). */
+    async deploy(appId, input, opts = {}) {
+        return this.deps.http.post(this.path(appId, "", {}), { ...input, space: opts.space });
+    }
+    /** Update a function's editor-settable fields and/or redeploy its `code`. */
+    async update(appId, functionId, patch, opts = {}) {
+        return this.deps.http.patch(this.path(appId, `/${encodeURIComponent(functionId)}`, {}), { ...patch, space: opts.space });
+    }
+    /** Delete a function (owner/editor only). */
+    async delete(appId, functionId, opts = {}) {
+        return this.deps.http.del(this.path(appId, `/${encodeURIComponent(functionId)}`, {}), { space: opts.space });
+    }
+    /** Enable the function on a Space (per-Space opt-in for the `space` trigger). */
+    async enable(appId, functionId, spaceId, opts = {}) {
+        return this.deps.http.post(this.path(appId, `/${encodeURIComponent(functionId)}/enable`, {}), { targetSpaceId: spaceId, space: opts.space });
+    }
+    /** Disable the function on a Space. */
+    async disable(appId, functionId, spaceId, opts = {}) {
+        return this.deps.http.post(this.path(appId, `/${encodeURIComponent(functionId)}/disable`, {}), { targetSpaceId: spaceId, space: opts.space });
+    }
+    path(appId, suffix, opts) {
+        const q = opts.space ? `?space=${encodeURIComponent(opts.space)}` : "";
+        return `/api/apps/${encodeURIComponent(appId)}/functions${suffix}${q}`;
+    }
+}
+
 /**
  * `Client` — the single entry point to the Muhkoo SDK.
  *
@@ -5995,14 +6743,24 @@ class Client {
     baseUrl;
     /** Authentication — `client.auth.zk.login(...)`, etc. */
     auth;
-    /** Per-user persistent storage — `client.storage.set(...)`, etc. */
+    /** Per-user key/value storage — `client.kv.set(...)`, etc. */
+    kv;
+    /** File storage — `client.storage.writeFile(...)`, etc. */
     storage;
     /** Realtime messaging — `client.message.subscribe(...)`, etc. */
     message;
     /** Fan-out group spaces — `client.space.createSpace(...)`, etc. */
     space;
+    /** Programmable Agents — `client.agents.create(appId, …)`, etc. */
+    agents;
+    /** Serverless functions — `client.functions.deploy(appId, …)`, etc. */
+    functions;
     session;
     http;
+    /** Subscribers notified when a session expires and can't be recovered. */
+    sessionExpiredHandlers = new Set();
+    /** Shared in-flight recovery so a burst of 401s triggers one re-auth. */
+    recoverInFlight = null;
     constructor(options = {}) {
         if (options.logLevel && typeof globalThis.appLogger?.setLevel === "function") {
             globalThis.appLogger.setLevel(options.logLevel);
@@ -6014,19 +6772,24 @@ class Client {
             apiKey: options.apiKey,
             getSessionToken: () => this.session.token,
             fetch: options.fetch,
+            // Self-heal stale sessions: on a 401, try a silent re-auth (only
+            // works while unlocked). If it can't, `recoverSession` fires the
+            // session-expired event so the app can redirect to login.
+            onUnauthorized: () => this.recoverSession(),
         });
         const circuits = options.circuits ?? defaultCircuitUrls(this.baseUrl);
         const authClient = new AuthClient({ baseUrl: this.baseUrl, fetch: this.http.fetch });
         const wsBaseUrl = toWsBase(this.baseUrl);
         this.auth = new AuthNamespace({ auth: authClient, circuits, session: this.session });
-        this.storage = new StorageNamespace({ http: this.http, session: this.session, wsBaseUrl });
+        this.kv = new KvNamespace({ http: this.http, session: this.session, wsBaseUrl });
+        this.storage = new StorageNamespace({ http: this.http, baseUrl: this.baseUrl, kv: this.kv });
         this.message = new MessageNamespace({ http: this.http, session: this.session, wsBaseUrl });
         // Group keys are cached in the user's PersonalSpace (encrypted at rest
-        // by StorageNamespace), so a returning member hydrates without a fresh
-        // keyring round-trip. The server only ever sees the ciphertext.
+        // by client.kv), so a returning member hydrates without a fresh keyring
+        // round-trip. The server only ever sees the ciphertext.
         const spaceKeyCache = {
-            loadKeys: (spaceId) => this.storage.get("space-keys", spaceId),
-            saveKeys: (spaceId, keys) => this.storage.set("space-keys", spaceId, keys),
+            loadKeys: (spaceId) => this.kv.get("space-keys", spaceId),
+            saveKeys: (spaceId, keys) => this.kv.set("space-keys", spaceId, keys),
         };
         this.space = new SpaceNamespace({
             http: this.http,
@@ -6034,6 +6797,8 @@ class Client {
             wsBaseUrl,
             cache: spaceKeyCache,
         });
+        this.agents = new AgentsNamespace({ http: this.http });
+        this.functions = new FunctionsNamespace({ http: this.http });
     }
     /** The currently signed-in user, or `null`. */
     get user() {
@@ -6043,6 +6808,48 @@ class Client {
     get isAuthenticated() {
         return this.session.isAuthenticated;
     }
+    /**
+     * Subscribe to session expiry that couldn't be silently recovered (the
+     * user's identity wasn't in memory to re-prove — typically after a reload
+     * where only the token was persisted, and that token has since gone stale).
+     * This is the signal to send the user back to the login screen.
+     *
+     * Returns an unsubscribe function.
+     *
+     *   const off = client.onSessionExpired(() => router.push('/login'));
+     */
+    onSessionExpired(handler) {
+        this.sessionExpiredHandlers.add(handler);
+        return () => this.sessionExpiredHandlers.delete(handler);
+    }
+    /**
+     * Attempt a silent re-auth of the current user. Concurrent callers share a
+     * single in-flight attempt (a stale token usually 401s several requests at
+     * once — we re-auth once, not once per request). On failure the
+     * session-expired event fires so the app can react. Exposed so apps can
+     * also drive recovery proactively (e.g. on `visibilitychange`).
+     */
+    recoverSession() {
+        if (this.recoverInFlight)
+            return this.recoverInFlight;
+        this.recoverInFlight = this.auth.zk
+            .recover()
+            .then((ok) => {
+            if (!ok) {
+                for (const handler of this.sessionExpiredHandlers) {
+                    try {
+                        handler();
+                    }
+                    catch { /* a bad listener mustn't break recovery */ }
+                }
+            }
+            return ok;
+        })
+            .finally(() => {
+            this.recoverInFlight = null;
+        });
+        return this.recoverInFlight;
+    }
 }
 
 const appLogger$1 = new Logger("connect", 'ERROR');
@@ -6351,7 +7158,7 @@ function alloc(u32, size) {
  * a convenient way to passphrase-encrypt a payload before putting it.
  */
 let _snarkjs = null;
-async function loadSnarkjs$1() {
+async function loadSnarkjs() {
     if (_snarkjs)
         return _snarkjs;
     _snarkjs = (await import('snarkjs'));
@@ -6365,21 +7172,21 @@ async function loadSnarkjs$1() {
  * Must stay in sync with the `nonce` public-signal width used by both
  * accelerator's `verifyZkAuthProof` and the `preimagePoK` circuit.
  */
-const FIELD_SIZE$1 = 21888242871839275222246405745257275088548364400416034343698204186575808495617n;
+const FIELD_SIZE = 21888242871839275222246405745257275088548364400416034343698204186575808495617n;
 /**
  * Reduce a hex nonce into a BN254 field-element decimal string, matching what
  * the Circom circuit expects as the `nonce` public signal.
  */
-function nonceHexToFieldString$1(nonceHex) {
+function nonceHexToFieldString(nonceHex) {
     const hex = nonceHex.startsWith("0x") ? nonceHex : "0x" + nonceHex;
-    return (BigInt(hex) % FIELD_SIZE$1).toString();
+    return (BigInt(hex) % FIELD_SIZE).toString();
 }
 /**
  * Read the response body as JSON, falling back to text for the error message
  * when the body isn't JSON. Centralized so every method handles failures the
  * same way.
  */
-async function parseOrThrow$1(response, label) {
+async function parseOrThrow(response, label) {
     if (!response.ok) {
         let detail = "";
         try {
@@ -6435,7 +7242,7 @@ class PersonalSpaceClient {
         const url = `${this.baseUrl}/api/personal/${encodeURIComponent(this.commitment)}/kv/${encodeURIComponent(key)}`;
         const body = { challengeId, proof, publicSignals, value };
         const response = await this.fetch(url, "POST", body);
-        await parseOrThrow$1(response, `put(${key})`);
+        await parseOrThrow(response, `put(${key})`);
     }
     /** Fetch the value stored under `key`. Returns `null` if absent. */
     async get(key) {
@@ -6443,7 +7250,7 @@ class PersonalSpaceClient {
         const url = `${this.baseUrl}/api/personal/${encodeURIComponent(this.commitment)}/kv/${encodeURIComponent(key)}/get`;
         const body = { challengeId, proof, publicSignals };
         const response = await this.fetch(url, "POST", body);
-        const data = await parseOrThrow$1(response, `get(${key})`);
+        const data = await parseOrThrow(response, `get(${key})`);
         return data.value ?? null;
     }
     /** Remove `key` from the user's space. Returns whether the key existed. */
@@ -6452,7 +7259,7 @@ class PersonalSpaceClient {
         const url = `${this.baseUrl}/api/personal/${encodeURIComponent(this.commitment)}/kv/${encodeURIComponent(key)}`;
         const body = { challengeId, proof, publicSignals };
         const response = await this.fetch(url, "DELETE", body);
-        const data = await parseOrThrow$1(response, `delete(${key})`);
+        const data = await parseOrThrow(response, `delete(${key})`);
         return data.existed;
     }
     /** List every key currently stored in the user's space. */
@@ -6461,7 +7268,7 @@ class PersonalSpaceClient {
         const url = `${this.baseUrl}/api/personal/${encodeURIComponent(this.commitment)}/list`;
         const body = { challengeId, proof, publicSignals };
         const response = await this.fetch(url, "POST", body);
-        const data = await parseOrThrow$1(response, "list()");
+        const data = await parseOrThrow(response, "list()");
         return Array.isArray(data.keys) ? data.keys : [];
     }
     // -------------------------------------------------------------------------
@@ -6474,7 +7281,7 @@ class PersonalSpaceClient {
      */
     async proveFreshChallenge() {
         const challenge = await this.requestChallenge();
-        const nonceField = nonceHexToFieldString$1(challenge.nonce);
+        const nonceField = nonceHexToFieldString(challenge.nonce);
         // Inputs to the `preimagePoK` circuit. Public signals are
         // `[commitment, nonce, ecdsaPubHash]`; the rest are private witnesses.
         const input = {
@@ -6485,7 +7292,7 @@ class PersonalSpaceClient {
             salt: this.salt,
             ecdsaPub: this.ecdsaPub,
         };
-        const snarkjs = await loadSnarkjs$1();
+        const snarkjs = await loadSnarkjs();
         const { proof, publicSignals } = await snarkjs.groth16.fullProve(input, this.wasmUrl, this.zkeyUrl);
         return {
             challengeId: challenge.challengeId,
@@ -6497,7 +7304,7 @@ class PersonalSpaceClient {
     async requestChallenge() {
         const url = `${this.baseUrl}/api/personal/${encodeURIComponent(this.commitment)}/challenge`;
         const response = await this.fetch(url, "POST", {});
-        return await parseOrThrow$1(response, "challenge");
+        return await parseOrThrow(response, "challenge");
     }
     /**
      * Thin wrapper over `globalThis.fetch` so all methods share a single set of
@@ -6518,251 +7325,6 @@ class PersonalSpaceClient {
     }
 }
 
-/**
- * HTTP client for the multi-user `SharedSpaceDO` (Phase B).
- *
- * Mirrors the proven shape of `PersonalSpaceClient` — every gated call:
- *   1. POSTs `/challenge` to get a fresh nonce keyed to the caller's commitment
- *   2. Generates a Groth16 proof for the `preimagePoK` circuit with the nonce
- *      reduced into a BN254 field element as the public signal
- *   3. POSTs the operation with `{ challengeId, proof, publicSignals, ... }`
- *
- * What's different from `PersonalSpaceClient`:
- *   - Addressed by space ID, not user commitment. Multiple users can be
- *     members of the same space.
- *   - The space carries a participants list + ACL (shared types from
- *     `src/types/permissions.ts`). The server checks that the proving
- *     commitment is a participant with the requested permission before each
- *     mutation.
- *   - Stores file manifests (not generic KV blobs). The shape is constrained
- *     by `FileManifest` from `../types`.
- *
- * Wire protocol (this client implements the client side; the server side is
- * the next slice of work in accelerator):
- *
- *   POST /api/spaces                                 create a new space (gated by caller proof)
- *     body: { challengeId, proof, publicSignals, initialAcl? }
- *     returns: { spaceId }
- *
- *   POST /api/spaces/:spaceId/challenge              issue a nonce for the caller
- *     body: { commitment }
- *     returns: { challengeId, nonce }
- *
- *   POST /api/spaces/:spaceId/files                  write a file manifest
- *     body: { challengeId, proof, publicSignals, manifest }
- *     returns: { ok: true, fileId }
- *
- *   POST /api/spaces/:spaceId/files/:fileId/get      read a file manifest
- *     body: { challengeId, proof, publicSignals }
- *     returns: { manifest }
- *
- *   DELETE /api/spaces/:spaceId/files/:fileId        delete a file manifest
- *     body: { challengeId, proof, publicSignals }
- *     returns: { ok: true, existed: boolean }
- *
- *   POST /api/spaces/:spaceId/files/list             list manifests in space
- *     body: { challengeId, proof, publicSignals }
- *     returns: { files: FileStat[] }
- *
- *   POST /api/spaces/:spaceId/participants           add a participant
- *     body: { challengeId, proof, publicSignals, participant: Participant }
- *     returns: { ok: true }
- *
- *   DELETE /api/spaces/:spaceId/participants/:commitment   remove a participant
- *     body: { challengeId, proof, publicSignals }
- *     returns: { ok: true, existed: boolean }
- *
- *   POST /api/spaces/:spaceId/acl                    set / replace an ACL entry
- *     body: { challengeId, proof, publicSignals, entry: ACLEntry }
- *     returns: { ok: true }
- */
-let snarkjsModule = null;
-async function loadSnarkjs() {
-    if (snarkjsModule)
-        return snarkjsModule;
-    snarkjsModule = (await import('snarkjs'));
-    return snarkjsModule;
-}
-// BN254 scalar field modulus — same value used everywhere else in the ZK path.
-const FIELD_SIZE = 21888242871839275222246405745257275088548364400416034343698204186575808495617n;
-class SharedSpaceClient {
-    baseUrl;
-    commitment;
-    secret;
-    salt;
-    ecdsaPub;
-    ecdsaPubHash;
-    wasmUrl;
-    zkeyUrl;
-    fetchFn;
-    constructor(opts) {
-        if (!opts?.baseUrl)
-            throw new Error("SharedSpaceClient: `baseUrl` is required");
-        if (!opts.commitment)
-            throw new Error("SharedSpaceClient: `commitment` is required");
-        if (!opts.secret)
-            throw new Error("SharedSpaceClient: `secret` is required");
-        if (!opts.salt)
-            throw new Error("SharedSpaceClient: `salt` is required");
-        if (!opts.ecdsaPub)
-            throw new Error("SharedSpaceClient: `ecdsaPub` is required");
-        if (!opts.ecdsaPubHash)
-            throw new Error("SharedSpaceClient: `ecdsaPubHash` is required");
-        if (!opts.circuits?.wasmUrl || !opts.circuits?.zkeyUrl) {
-            throw new Error("SharedSpaceClient: `circuits.wasmUrl` and `circuits.zkeyUrl` are required");
-        }
-        this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
-        this.commitment = opts.commitment;
-        this.secret = opts.secret;
-        this.salt = opts.salt;
-        this.ecdsaPub = opts.ecdsaPub;
-        this.ecdsaPubHash = opts.ecdsaPubHash;
-        this.wasmUrl = opts.circuits.wasmUrl;
-        this.zkeyUrl = opts.circuits.zkeyUrl;
-        const f = opts.fetch ?? globalThis.fetch;
-        if (typeof f !== "function") {
-            throw new Error("SharedSpaceClient: `globalThis.fetch` is unavailable; pass an explicit fetch.");
-        }
-        this.fetchFn = f.bind(globalThis);
-    }
-    /**
-     * Create a brand new space. The caller becomes the owner; `initialAcl`
-     * adds any additional ACL entries up front (e.g. inviting a co-owner at
-     * creation time).
-     */
-    async createSpace(initialAcl) {
-        // Creating a space still requires the caller to prove they hold the
-        // commitment they're claiming to own — that's what the proof
-        // accomplishes here. The server issues a challenge against a global
-        // "newspace" pseudo-id for the bootstrap step.
-        const proof = await this.proveFreshChallenge("__new__");
-        const body = { ...proof };
-        if (initialAcl)
-            body.initialAcl = initialAcl;
-        const url = `${this.baseUrl}/api/spaces`;
-        const response = await this.fetchFn(url, this.jsonRequest("POST", body));
-        const data = await parseOrThrow(response, "createSpace");
-        return { spaceId: data.spaceId };
-    }
-    /** Write a file manifest into the space. Requires `write` permission. */
-    async writeFileManifest(spaceId, manifest) {
-        const proof = await this.proveFreshChallenge(spaceId);
-        const body = { ...proof, manifest };
-        const url = `${this.baseUrl}/api/spaces/${encodeURIComponent(spaceId)}/files`;
-        const response = await this.fetchFn(url, this.jsonRequest("POST", body));
-        await parseOrThrow(response, `writeFileManifest(${manifest.id})`);
-    }
-    /** Read a file manifest by id. Requires `read` permission. */
-    async readFileManifest(spaceId, fileId) {
-        const proof = await this.proveFreshChallenge(spaceId);
-        const body = { ...proof };
-        const url = `${this.baseUrl}/api/spaces/${encodeURIComponent(spaceId)}/files/${encodeURIComponent(fileId)}/get`;
-        const response = await this.fetchFn(url, this.jsonRequest("POST", body));
-        const data = await parseOrThrow(response, `readFileManifest(${fileId})`);
-        return data.manifest;
-    }
-    /** Delete a file manifest by id. Requires `delete` permission. */
-    async deleteFileManifest(spaceId, fileId) {
-        const proof = await this.proveFreshChallenge(spaceId);
-        const body = { ...proof };
-        const url = `${this.baseUrl}/api/spaces/${encodeURIComponent(spaceId)}/files/${encodeURIComponent(fileId)}`;
-        const response = await this.fetchFn(url, this.jsonRequest("DELETE", body));
-        const data = await parseOrThrow(response, `deleteFileManifest(${fileId})`);
-        return data.existed;
-    }
-    /** List file summaries in the space. Requires `read` permission. */
-    async listFiles(spaceId) {
-        const proof = await this.proveFreshChallenge(spaceId);
-        const body = { ...proof };
-        const url = `${this.baseUrl}/api/spaces/${encodeURIComponent(spaceId)}/files/list`;
-        const response = await this.fetchFn(url, this.jsonRequest("POST", body));
-        const data = await parseOrThrow(response, "listFiles");
-        return Array.isArray(data.files) ? data.files : [];
-    }
-    /** Add a participant. Requires `invite` or `admin`. */
-    async addParticipant(spaceId, participant) {
-        const proof = await this.proveFreshChallenge(spaceId);
-        const body = { ...proof, participant };
-        const url = `${this.baseUrl}/api/spaces/${encodeURIComponent(spaceId)}/participants`;
-        const response = await this.fetchFn(url, this.jsonRequest("POST", body));
-        await parseOrThrow(response, "addParticipant");
-    }
-    /** Remove a participant by their public-key identity. Requires `admin`. */
-    async removeParticipant(spaceId, participantCommitment) {
-        const proof = await this.proveFreshChallenge(spaceId);
-        const body = { ...proof };
-        const url = `${this.baseUrl}/api/spaces/${encodeURIComponent(spaceId)}/participants/${encodeURIComponent(participantCommitment)}`;
-        const response = await this.fetchFn(url, this.jsonRequest("DELETE", body));
-        const data = await parseOrThrow(response, "removeParticipant");
-        return data.existed;
-    }
-    /** Set / replace an ACL entry. Requires `admin`. */
-    async setACLEntry(spaceId, entry) {
-        const proof = await this.proveFreshChallenge(spaceId);
-        const body = { ...proof, entry };
-        const url = `${this.baseUrl}/api/spaces/${encodeURIComponent(spaceId)}/acl`;
-        const response = await this.fetchFn(url, this.jsonRequest("POST", body));
-        await parseOrThrow(response, "setACLEntry");
-    }
-    // -------------------------------------------------------------------------
-    // Internals
-    // -------------------------------------------------------------------------
-    /** Request a challenge for `spaceId` and generate the matching proof. */
-    async proveFreshChallenge(spaceId) {
-        const challenge = await this.requestChallenge(spaceId);
-        const nonceField = nonceHexToFieldString(challenge.nonce);
-        const input = {
-            commitment: this.commitment,
-            nonce: nonceField,
-            ecdsaPubHash: this.ecdsaPubHash,
-            secret: this.secret,
-            salt: this.salt,
-            ecdsaPub: this.ecdsaPub,
-        };
-        const snarkjs = await loadSnarkjs();
-        const { proof, publicSignals } = await snarkjs.groth16.fullProve(input, this.wasmUrl, this.zkeyUrl);
-        return {
-            challengeId: challenge.challengeId,
-            proof: proof,
-            publicSignals: publicSignals,
-        };
-    }
-    /**
-     * Hit `/challenge`. The body includes the caller's commitment so the
-     * server can scope the issued nonce to this principal.
-     */
-    async requestChallenge(spaceId) {
-        const url = `${this.baseUrl}/api/spaces/${encodeURIComponent(spaceId)}/challenge`;
-        const response = await this.fetchFn(url, this.jsonRequest("POST", { commitment: this.commitment }));
-        return await parseOrThrow(response, "challenge");
-    }
-    jsonRequest(method, body) {
-        return {
-            method,
-            headers: { "content-type": "application/json" },
-            body: JSON.stringify(body ?? {}),
-        };
-    }
-}
-function nonceHexToFieldString(nonceHex) {
-    const hex = nonceHex.startsWith("0x") ? nonceHex : "0x" + nonceHex;
-    return (BigInt(hex) % FIELD_SIZE).toString();
-}
-async function parseOrThrow(response, label) {
-    if (!response.ok) {
-        let detail = "";
-        try {
-            const text = await response.text();
-            detail = text ? `: ${text}` : "";
-        }
-        catch {
-            // ignore — we still throw with the status
-        }
-        throw new Error(`SharedSpaceClient ${label} failed (${response.status})${detail}`);
-    }
-    return (await response.json());
-}
-
 /**
  * PacketCipher — the strategy `Network` uses to seal/open a packet's payload.
  *
@@ -6826,5 +7388,5 @@ var bundledLoader = /*#__PURE__*/Object.freeze({
     default: loadRsWasm
 });
 
-export { AES_GCM_IV_BYTES, AES_GCM_KEY_BYTES, AES_GCM_TAG_BYTES, AuthClient, AuthNamespace, AuthPublicInput, Authenticator, BroadcastChannel, BroadcastChannelEvents, ChannelExistsError, ChannelNotFoundError, ChunkCipher, Client, DEFAULT_BASE_URL, DoubleRatchet, DoubleRatchetCipher, DoubleRatchetManager, EncryptedSession, EventCore, EventCoreEvents, Field, Field as FieldElement, FileStorage, HashKnowledge, HttpClient, HttpError, KEEPER_MEMBER_ID, KeyStore, KeyringClient, LocalStorageSessionStore, Logger, MemorySessionStore, Message, Message as MessageDefault, MessageNamespace, PBKDF2_DEFAULT_ITERATIONS, PREIMAGE_POK_VERIFICATION_KEY, Packet, PersonalSpaceClient, Poseidon, PreimagePoK, Ready, ReedSolomonCodec, Retry, Space as Room, SerializeMessage, SessionState, ShardClient, SharedSpaceClient, Space, SpaceKeyring, SpaceNamespace, SpacePacketCipher, StorageNamespace, WSTransport, ZkAuth, _accountId, _formatBytes, _messageId, _objectId, _packetId, _socketId, _userId, appLogger$1 as appLogger, assertType, base58Decode, base58Encode, buildCommitment, compilePrograms, concatBytes, decodeFromHex, decorators, decryptAesGcm, defaultCircuitUrls, defaultSessionStore, deriveAesKeyFromPassphrase, deriveBitsHkdf, deriveIdentity, deserialize, encodeToHex, encryptAesGcm, exportPublicKeyBase64, exportPublicKeyHex, fromBase64, fromBase64Url, fromHex, generateAuthProof, generateChecksum, generateId, getIPAddress, getId, getSubtle, initBn128Wasm, initRsWasm, initializeCircuits, isNumber, log, manifestToStat, poseidonHash, quickVerify, randomBytes, serialize, shardHash, signMessage, toBase64, toBase64Url, toField, toHex, unwrapWithPassphrase, utf8Decode, utf8Encode, verify, verifyChecksum, verifyGroth16, verifyHashKnowledge, verifyPreimagePoK, wrapWithPassphrase };
+export { AES_GCM_IV_BYTES, AES_GCM_KEY_BYTES, AES_GCM_TAG_BYTES, AgentsNamespace, AuthClient, AuthNamespace, AuthPublicInput, Authenticator, BroadcastChannel, BroadcastChannelEvents, ChannelExistsError, ChannelNotFoundError, ChunkCipher, Client, DEFAULT_BASE_URL, DoubleRatchet, DoubleRatchetCipher, DoubleRatchetManager, EncryptedSession, EventCore, EventCoreEvents, Field, Field as FieldElement, FileStorage, FunctionsNamespace, HashKnowledge, HttpClient, HttpError, KEEPER_MEMBER_ID, KeyStore, KeyringClient, KvNamespace, LocalStorageSessionStore, Logger, MemorySessionStore, Message, Message as MessageDefault, MessageNamespace, PBKDF2_DEFAULT_ITERATIONS, PREIMAGE_POK_VERIFICATION_KEY, Packet, PersonalSpaceClient, Poseidon, PreimagePoK, Ready, ReedSolomonCodec, Retry, Space as Room, SerializeMessage, SessionState, ShardClient, SharedSpaceClient, Space, SpaceKeyring, SpaceNamespace, SpacePacketCipher, StorageNamespace, WSTransport, ZkAuth, _accountId, _formatBytes, _messageId, _objectId, _packetId, _socketId, _userId, appLogger$1 as appLogger, assertType, base58Decode, base58Encode, buildCommitment, compilePrograms, concatBytes, decodeFromHex, decorators, decryptAesGcm, defaultCircuitUrls, defaultSessionStore, deriveAesKeyFromPassphrase, deriveBitsHkdf, deriveIdentity, deserialize, encodeToHex, encryptAesGcm, exportPublicKeyBase64, exportPublicKeyHex, fromBase64, fromBase64Url, fromHex, generateAuthProof, generateChecksum, generateId, getIPAddress, getId, getSubtle, initBn128Wasm, initRsWasm, initializeCircuits, isNumber, log, manifestToStat, poseidonHash, quickVerify, randomBytes, serialize, shardHash, signMessage, toBase64, toBase64Url, toField, toHex, unwrapWithPassphrase, utf8Decode, utf8Encode, verify, verifyChecksum, verifyGroth16, verifyHashKnowledge, verifyPreimagePoK, wrapWithPassphrase };
 //# sourceMappingURL=index.js.map