@muhkoo/connect 0.2.0-alpha.1 → 0.3.0-alpha.0

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`.");
@@ -2791,7 +2793,7 @@ class HttpClient {
     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 +2801,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 +3039,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 +3233,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,10 +3248,29 @@ 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;
     socket = null;
     _isConnected = false;
@@ -3354,16 +3284,28 @@ 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.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() {
@@ -3381,9 +3323,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 +3350,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 +3369,7 @@ class WSTransport extends EventCore {
             clearTimeout(this.reconnectTimeout);
             this.reconnectTimeout = null;
         }
+        this.stopHeartbeat();
         this.autoReconnect = false;
         if (this.socket) {
             try {
@@ -3446,6 +3400,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) {
@@ -3481,473 +3507,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);
+    }
+    /** 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.kv.query is not implemented yet (deferred in the SDK overhaul).");
     }
     /**
-     * Generate this client's ECDH + ECDSA keypair (idempotent — safe to call
-     * multiple times across reconnects; only the first call generates).
+     * 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).
      */
-    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");
+    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 {
-            keyExchange: {
-                type: "handshake",
-                userId: this.myId,
-                ecdhPublicKey: await exportJwkBase64(ownEcdh.publicKey),
-                ecdsaPublicKey: await exportJwkBase64(ownEcdsa.publicKey),
-            },
+        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();
         };
     }
-    /**
-     * 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 };
+    // -------------------------------------------------------------------------
+    // 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
@@ -4091,662 +3804,1352 @@ function getArrayJsValueFromWasm(ptr, len) {
     for (let i = 0; i < slice.length; i++) {
         result.push(takeObject(slice[i]));
     }
-    return result;
-}
-function getStringFromWasm(ptr, len) {
-    return textDecoder.decode(u8().subarray(ptr, ptr + len));
+    return result;
+}
+function getStringFromWasm(ptr, len) {
+    return textDecoder.decode(u8().subarray(ptr, ptr + len));
+}
+/**
+ * The wbindgen import object — every callback Rust expects from JS. Names are
+ * hard-coded by wasm-bindgen based on the Rust function signatures; do not
+ * rename. If the upstream package is regenerated, these may drift and need
+ * resyncing with the new `wasm_reed_solomon_erasure.js`.
+ */
+function buildImports() {
+    const wbindgen = {
+        __wbindgen_object_drop_ref: (arg0) => {
+            takeObject(arg0);
+        },
+        __wbg_buffer_7af23f65f6c64548: (arg0) => {
+            const ret = getObject(arg0).buffer;
+            return addHeapObject(ret);
+        },
+        __wbg_newwithbyteoffsetandlength_ce1e75f0ce5f7974: (arg0, arg1, arg2) => {
+            const ret = new Uint8Array(getObject(arg0), arg1 >>> 0, arg2 >>> 0);
+            return addHeapObject(ret);
+        },
+        __wbg_new_cc9018bd6f283b6f: (arg0) => {
+            const ret = new Uint8Array(getObject(arg0));
+            return addHeapObject(ret);
+        },
+        __wbg_set_f25e869e4565d2a2: (arg0, arg1, arg2) => {
+            getObject(arg0).set(getObject(arg1), arg2 >>> 0);
+        },
+        __wbg_length_0acb1cf9bbaf8519: (arg0) => {
+            return getObject(arg0).length;
+        },
+        __wbg_new_e8c5277c0f9e2cfc: (arg0) => {
+            const ret = new Uint32Array(getObject(arg0));
+            return addHeapObject(ret);
+        },
+        __wbg_set_03c7d8c063f469ef: (arg0, arg1, arg2) => {
+            getObject(arg0).set(getObject(arg1), arg2 >>> 0);
+        },
+        __wbg_length_f98ca60981480796: (arg0) => {
+            return getObject(arg0).length;
+        },
+        __wbindgen_throw: (arg0, arg1) => {
+            throw new Error(getStringFromWasm(arg0, arg1));
+        },
+        __wbindgen_memory: () => {
+            return addHeapObject(wasm.memory);
+        },
+    };
+    return { __wbindgen_placeholder__: wbindgen };
+}
+let _readyPromise = null;
+/**
+ * Load and instantiate the WASM module. Idempotent — repeated calls await the
+ * same one-shot promise.
+ *
+ * Two ways to initialize, matching the pattern used by `workers/groth16-verifier`:
+ *   1. `await initRsWasm()` — uses the bundled .wasm (base64-inlined at build
+ *      time by `@rollup/plugin-wasm`). Works in any runtime that allows
+ *      runtime `WebAssembly.compile()`.
+ *   2. `await initRsWasm(myWasmModule)` — accepts a pre-compiled
+ *      `WebAssembly.Module`. Useful when the bundled loader path isn't
+ *      available (vitest, CF Workers wanting deploy-time precompile, etc.).
+ */
+async function initRsWasm(wasmModule) {
+    if (_readyPromise)
+        return _readyPromise;
+    _readyPromise = (async () => {
+        const imports = buildImports();
+        let instance;
+        if (wasmModule) {
+            // `instantiate(module, imports)` returns a bare Instance.
+            instance = await WebAssembly.instantiate(wasmModule, imports);
+        }
+        else {
+            // Defer the `.wasm` import to a separate module so vitest can load
+            // `rs.ts` without it. Production callers either don't pass a
+            // module (and hit the bundled loader here) or pass one explicitly.
+            const bundled = (await Promise.resolve().then(function () { return bundledLoader; })).default;
+            const result = await bundled(imports);
+            // The bundled loader's actual return type is
+            // `{ module: WebAssembly.Module, instance: WebAssembly.Instance }`
+            // — the rollup-plugin-wasm shape from `WebAssembly.instantiate(buffer, imports)`.
+            // Older versions (or future changes) may return a bare Instance,
+            // so accept either shape.
+            instance = unwrapInstance(result);
+        }
+        wasm = instance.exports;
+    })();
+    return _readyPromise;
+}
+/**
+ * Normalize the value returned by `WebAssembly.instantiate` / the
+ * rollup-plugin-wasm loader into a bare `WebAssembly.Instance`. Handles
+ * both the `(module, imports)` overload (returns Instance) and the
+ * `(buffer, imports)` overload (returns `{ module, instance }`).
+ */
+function unwrapInstance(result) {
+    if (result && typeof result === "object") {
+        const candidate = result;
+        if (candidate.instance && typeof candidate.instance === "object" && "exports" in candidate.instance) {
+            return candidate.instance;
+        }
+        if ("exports" in candidate) {
+            return result;
+        }
+    }
+    throw new Error("rs.ts: bundled WASM loader returned an unrecognized shape — expected WebAssembly.Instance or { module, instance }");
+}
+function ensureReady() {
+    if (!wasm) {
+        throw new Error("rs.ts: WASM not initialized. Call `await initRsWasm()` first.");
+    }
+}
+// ---------------------------------------------------------------------------
+// Public API — encode + reconstruct
+// ---------------------------------------------------------------------------
+/**
+ * Encode the input data shards with `parityShard` parity shards. All input
+ * shards must be Uint8Arrays of equal length; output contains the input shards
+ * unchanged plus `parityShard` newly computed parity shards.
+ */
+function encode(dataShards, parityShard) {
+    ensureReady();
+    const w = wasm;
+    try {
+        const retptr = w.__wbindgen_add_to_stack_pointer(-16);
+        const ptr0 = passArrayJsValueToWasm(dataShards, w.__wbindgen_malloc);
+        const len0 = WASM_VECTOR_LEN;
+        w.encode(retptr, ptr0, len0, parityShard);
+        const r0 = i32()[retptr / 4 + 0];
+        const r1 = i32()[retptr / 4 + 1];
+        const v1 = getArrayJsValueFromWasm(r0, r1).slice();
+        w.__wbindgen_free(r0, r1 * 4);
+        return v1;
+    }
+    finally {
+        w.__wbindgen_add_to_stack_pointer(16);
+    }
+}
+/**
+ * Reconstruct the original full shard array. `corruptedShards` is the full
+ * list (data + parity) with placeholder Uint8Arrays at positions listed in
+ * `deadShardIndexes`. Returns the recovered, complete list of shards.
+ *
+ * Up to `parityShard` shards may be missing; more than that is uncorrectable
+ * and the underlying WASM throws.
+ */
+function reconstruct(corruptedShards, parityShard, deadShardIndexes) {
+    ensureReady();
+    const w = wasm;
+    try {
+        const retptr = w.__wbindgen_add_to_stack_pointer(-16);
+        const ptr0 = passArrayJsValueToWasm(corruptedShards, w.__wbindgen_malloc);
+        const len0 = WASM_VECTOR_LEN;
+        w.reconstruct(retptr, ptr0, len0, parityShard, addHeapObject(deadShardIndexes));
+        const r0 = i32()[retptr / 4 + 0];
+        const r1 = i32()[retptr / 4 + 1];
+        const v1 = getArrayJsValueFromWasm(r0, r1).slice();
+        w.__wbindgen_free(r0, r1 * 4);
+        return v1;
+    }
+    finally {
+        w.__wbindgen_add_to_stack_pointer(16);
+    }
+}
+
+/**
+ * Reed–Solomon erasure-coding codec.
+ *
+ * Wraps the WASM-backed `encode` / `reconstruct` primitives in `wasm/rs.ts`
+ * with shard-padding bookkeeping so callers can hand it any-length input and
+ * get back uniform-size shards.
+ *
+ * Usage:
+ *   const codec = new ReedSolomonCodec();
+ *   await codec.ready();
+ *   const { shards, shardSize, originalSize } = codec.encode(plaintext, 4, 2);
+ *   // 6 shards (4 data + 2 parity), each `shardSize` bytes
+ *   // …ship them, lose up to 2, then …
+ *   const recovered = codec.decode(shards, 2, deadIndexes, originalSize);
+ *
+ * Why the explicit `originalSize`: RS pads input to make every data shard the
+ * same length. The decoder must trim that padding back off after recovery.
+ * The caller is responsible for stashing `originalSize` somewhere durable
+ * (the file manifest, in this codebase).
+ */
+class ReedSolomonCodec {
+    /**
+     * Resolves once the WASM module is loaded; safe to call repeatedly.
+     *
+     * Pass `wasmModule` to use a pre-compiled module (e.g. in tests where the
+     * rollup-inlined loader path isn't available, or in CF Workers where you
+     * want to load the module at deploy time). Default path uses the bundled
+     * base64-inlined wasm — works in Node, browsers, and Workers.
+     */
+    ready(wasmModule) {
+        return initRsWasm(wasmModule);
+    }
+    /**
+     * Split `data` into `dataShards` equal-size chunks (zero-padded to fit),
+     * compute `parityShards` parity shards, and return all of them.
+     */
+    encode(data, dataShards, parityShards) {
+        if (dataShards < 1)
+            throw new Error("ReedSolomonCodec.encode: dataShards must be >= 1");
+        if (parityShards < 1)
+            throw new Error("ReedSolomonCodec.encode: parityShards must be >= 1");
+        if (data.length === 0)
+            throw new Error("ReedSolomonCodec.encode: data is empty");
+        // The wbindgen-generated WASM in `wasm-reed-solomon-erasure@0.2.2` takes
+        // the `parity_shard` count separately and infers `total = data.length +
+        // parity_shard`. Every shard must be the same length, so we pad the
+        // input to `dataShards * shardSize` with trailing zeros.
+        const shardSize = Math.ceil(data.length / dataShards);
+        const splitInputs = [];
+        for (let i = 0; i < dataShards; i++) {
+            // Each shard is its own backing ArrayBuffer so the WASM side
+            // doesn't observe overlapping views (which would confuse the
+            // wbindgen length lookups).
+            const shard = new Uint8Array(shardSize);
+            const start = i * shardSize;
+            const end = Math.min(start + shardSize, data.length);
+            if (start < data.length) {
+                shard.set(data.subarray(start, end));
+            }
+            splitInputs.push(shard);
+        }
+        const shards = encode(splitInputs, parityShards);
+        // The underlying call returns N+M shards; first N are the (padded)
+        // data shards we just sent in, last M are the parity shards.
+        return {
+            shards,
+            shardSize,
+            originalSize: data.length,
+            dataShards,
+            parityShards,
+        };
+    }
+    /**
+     * Reconstruct the original `data` from `shards`. Up to `parityShards`
+     * shards may be missing; for each missing shard, pass an empty
+     * `Uint8Array` placeholder at its position and list the position in
+     * `deadShardIndexes`.
+     *
+     * `originalSize` is required so the trailing zero-padding can be trimmed.
+     */
+    decode(shards, parityShards, deadShardIndexes, originalSize) {
+        if (parityShards < 1)
+            throw new Error("ReedSolomonCodec.decode: parityShards must be >= 1");
+        if (shards.length <= parityShards) {
+            throw new Error("ReedSolomonCodec.decode: shards.length must be > parityShards");
+        }
+        if (deadShardIndexes.length > parityShards) {
+            throw new Error(`ReedSolomonCodec.decode: too many missing shards (${deadShardIndexes.length} > ${parityShards})`);
+        }
+        const dataShards = shards.length - parityShards;
+        const recovered = deadShardIndexes.length === 0
+            ? shards
+            : reconstruct(shards, parityShards, new Uint32Array(deadShardIndexes));
+        // Concatenate the leading `dataShards`, then trim padding back off.
+        const shardSize = recovered[0]?.length ?? 0;
+        const out = new Uint8Array(dataShards * shardSize);
+        for (let i = 0; i < dataShards; i++) {
+            out.set(recovered[i], i * shardSize);
+        }
+        return out.subarray(0, originalSize);
+    }
+}
+
+/**
+ * HTTP client for the open content-addressed shard store.
+ *
+ * Each shard is named by the lowercase hex SHA-256 of its ciphertext bytes.
+ * The server verifies the hash on PUT, so the address authenticates the
+ * contents — there's no benefit to ACLing PUT/GET, and making them open
+ * enables cross-user dedup down the line.
+ *
+ * Wire protocol:
+ *   PUT  /api/shards/:hash    body: shard bytes (application/octet-stream)
+ *                             200 { ok: true, hash, size, dedup: boolean }
+ *                             400 if hash doesn't match body
+ *
+ *   GET  /api/shards/:hash    200 with shard bytes (application/octet-stream)
+ *                             404 if absent
+ *
+ *   HEAD /api/shards/:hash    200 if present (no body) — used by callers to
+ *                             skip a PUT they'd otherwise dedup-rewrite. The
+ *                             server can ignore the optimization if it wants.
+ */
+/**
+ * Compute the lowercase hex SHA-256 of `bytes`. Available via WebCrypto in
+ * every runtime this SDK targets.
+ */
+async function shardHash(bytes) {
+    const subtle = globalThis.crypto?.subtle;
+    if (!subtle) {
+        throw new Error("shardHash: `globalThis.crypto.subtle` is unavailable in this runtime.");
+    }
+    const digest = await subtle.digest("SHA-256", bytes);
+    return toHex(new Uint8Array(digest));
+}
+class ShardClient {
+    baseUrl;
+    pathPrefix;
+    fetchFn;
+    constructor(opts) {
+        if (!opts?.baseUrl)
+            throw new Error("ShardClient: `baseUrl` is required");
+        // Strip trailing slash so url concatenation stays clean.
+        this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+        // Normalize prefix to leading-slash + no-trailing-slash form so the
+        // URL builder can blindly append `/{hash}`.
+        const rawPrefix = opts.pathPrefix ?? "/api/shards";
+        const withSlash = rawPrefix.startsWith("/") ? rawPrefix : `/${rawPrefix}`;
+        this.pathPrefix = withSlash.replace(/\/+$/, "");
+        const f = opts.fetch ?? globalThis.fetch;
+        if (typeof f !== "function") {
+            throw new Error("ShardClient: `globalThis.fetch` is unavailable; pass an explicit fetch.");
+        }
+        this.fetchFn = f.bind(globalThis);
+    }
+    /** Build the URL for a given shard hash — exposed for callers that want to log or pre-resolve. */
+    urlForHash(hash) {
+        return `${this.baseUrl}${this.pathPrefix}/${encodeURIComponent(hash)}`;
+    }
+    /**
+     * Upload a shard. The server verifies SHA-256(body) matches `:hash` and
+     * rejects with 400 if not, so the caller is the source of truth on
+     * naming. Re-uploading an existing shard is idempotent — the server
+     * returns `dedup: true` in that case.
+     */
+    async putShard(hash, bytes) {
+        const url = this.urlForHash(hash);
+        const response = await this.fetchFn(url, {
+            method: "PUT",
+            headers: { "content-type": "application/octet-stream" },
+            // BufferSource is what fetch's body expects; a Uint8Array satisfies it.
+            body: bytes,
+        });
+        if (!response.ok) {
+            const text = await safeText(response);
+            throw new Error(`ShardClient.putShard(${hash}) failed (${response.status}): ${text}`);
+        }
+        let dedup = false;
+        try {
+            const json = (await response.json());
+            dedup = Boolean(json?.dedup);
+        }
+        catch {
+            // Server returned 200 with no body — treat as fresh upload.
+        }
+        return { dedup };
+    }
+    /**
+     * Fetch a shard by hash. Throws if the server returns a non-200; returns
+     * `null` for 404 so callers can distinguish "missing" from "errored".
+     */
+    async getShard(hash) {
+        const url = this.urlForHash(hash);
+        const response = await this.fetchFn(url, { method: "GET" });
+        if (response.status === 404)
+            return null;
+        if (!response.ok) {
+            const text = await safeText(response);
+            throw new Error(`ShardClient.getShard(${hash}) failed (${response.status}): ${text}`);
+        }
+        const buf = await response.arrayBuffer();
+        return new Uint8Array(buf);
+    }
+    /**
+     * Check whether a shard exists. Lets the caller skip a PUT they'd otherwise
+     * dedup-rewrite. The server can implement this as a HEAD or return a small
+     * JSON body — we don't depend on either.
+     */
+    async hasShard(hash) {
+        const url = this.urlForHash(hash);
+        const response = await this.fetchFn(url, { method: "HEAD" });
+        return response.status === 200;
+    }
+}
+async function safeText(response) {
+    try {
+        return await response.text();
+    }
+    catch {
+        return "";
+    }
+}
+
+/**
+ * `FileStorage` — top-level entry point for chunked, encrypted, erasure-coded
+ * file storage.
+ *
+ * Pipeline for writing a file:
+ *   1. Split the plaintext into fixed-size chunks (default 4 MiB).
+ *   2. For each chunk:
+ *        a. Generate a fresh AES-256-GCM key + 12-byte IV (`ChunkCipher`).
+ *        b. Encrypt the chunk → ciphertext (plaintext.length + 16 bytes tag).
+ *        c. Reed–Solomon encode the ciphertext into `dataShards + parityShards`
+ *           equal-length shards (`ReedSolomonCodec`).
+ *        d. PUT every shard to the content-addressed shard store, keyed by
+ *           SHA-256 of the shard bytes (`ShardClient`).
+ *   3. Build a `FileManifest` listing every chunk's keys, IVs, sizes, and
+ *      the SHA-256 of every shard in order.
+ *
+ * Two ways to use the manifest:
+ *   - {@link FileStorage.writeFileToShards} returns it to the caller, who is
+ *     then responsible for delivering it to readers (e.g. by E2E-encrypting
+ *     it as a chat message). The chat application takes this path.
+ *   - {@link FileStorage.writeFile} additionally POSTs the manifest to a
+ *     gated multi-user space (`SharedSpaceClient`) so any participant of the
+ *     space can read the file by manifest id later.
+ *
+ * Reading is the inverse: {@link FileStorage.readFileFromShards} takes a
+ * manifest and reassembles the plaintext; {@link FileStorage.readFile} first
+ * fetches the manifest from the space.
+ */
+class FileStorage {
+    space;
+    shards;
+    chunkSize;
+    dataShards;
+    parityShards;
+    concurrency;
+    cipher = new ChunkCipher();
+    codec = new ReedSolomonCodec();
+    rsWasmModule;
+    constructor(opts) {
+        if (!opts?.shards)
+            throw new Error("FileStorage: `shards` (ShardClient) is required");
+        this.space = opts.space;
+        this.shards = opts.shards;
+        this.chunkSize = opts.chunkSize ?? 4 * 1024 * 1024;
+        this.dataShards = opts.dataShards ?? 4;
+        this.parityShards = opts.parityShards ?? 2;
+        this.concurrency = Math.max(1, opts.concurrency ?? 8);
+        this.rsWasmModule = opts.rsWasmModule;
+        if (this.chunkSize < 1)
+            throw new Error("FileStorage: chunkSize must be >= 1 byte");
+        if (this.dataShards < 1)
+            throw new Error("FileStorage: dataShards must be >= 1");
+        if (this.parityShards < 1)
+            throw new Error("FileStorage: parityShards must be >= 1");
+    }
+    // -------------------------------------------------------------------------
+    // Shard-only pipeline — the caller owns the manifest. Used by chat file
+    // sharing, where the manifest rides as an E2E-encrypted chat message.
+    // -------------------------------------------------------------------------
+    /**
+     * Chunk → encrypt → encode → upload-shards. Returns the resulting manifest
+     * along with a `FileStat` summary. The caller is responsible for storing
+     * or transmitting the manifest however it likes.
+     */
+    async writeFileToShards(input) {
+        await this.codec.ready(this.rsWasmModule);
+        const data = await toUint8Array(input.data);
+        const fileId = input.fileId ?? generateId();
+        const createdAt = Date.now();
+        const chunks = [];
+        // 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
+        // `this.concurrency`.
+        for (let chunkIndex = 0; chunkIndex * this.chunkSize < Math.max(1, data.length); chunkIndex++) {
+            const start = chunkIndex * this.chunkSize;
+            const end = Math.min(start + this.chunkSize, data.length);
+            const plaintext = data.subarray(start, end);
+            chunks.push(await this.writeChunk(plaintext, chunkIndex));
+            // 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)
+                break;
+        }
+        const manifest = {
+            id: fileId,
+            name: input.metadata.name,
+            size: data.length,
+            type: input.metadata.type,
+            path: input.metadata.path,
+            lastModified: input.metadata.lastModified ?? createdAt,
+            createdAt,
+            chunks,
+            version: 1,
+        };
+        return { manifest, stat: manifestToStat(manifest) };
+    }
+    /**
+     * Inverse of {@link writeFileToShards}. Takes a manifest the caller
+     * obtained somehow (chat message, share link, etc.) and reassembles the
+     * plaintext. Throws if too many shards are missing or any chunk's auth
+     * tag fails.
+     */
+    async readFileFromShards(manifest) {
+        await this.codec.ready(this.rsWasmModule);
+        // Materialize each chunk into plaintext, then concatenate. We don't
+        // stream across chunks here because the consuming surface returns
+        // `Uint8Array`; a streaming variant would reuse `readChunk` unchanged.
+        const plaintextChunks = [];
+        for (const chunkManifest of [...manifest.chunks].sort((a, b) => a.chunkIndex - b.chunkIndex)) {
+            plaintextChunks.push(await this.readChunk(chunkManifest));
+        }
+        let total = 0;
+        for (const c of plaintextChunks)
+            total += c.length;
+        const out = new Uint8Array(total);
+        let offset = 0;
+        for (const c of plaintextChunks) {
+            out.set(c, offset);
+            offset += c.length;
+        }
+        return { data: out, stat: manifestToStat(manifest) };
+    }
+    // -------------------------------------------------------------------------
+    // Space-backed convenience wrappers — encrypt + upload + write manifest.
+    // Require a `SharedSpaceClient` to have been provided at construction.
+    // -------------------------------------------------------------------------
+    /** As {@link writeFileToShards}, plus POSTs the manifest to `input.spaceId`. */
+    async writeFile(input) {
+        const space = this.requireSpace("writeFile");
+        const { manifest, stat } = await this.writeFileToShards(input);
+        await space.writeFileManifest(input.spaceId, manifest);
+        return stat;
+    }
+    /** As {@link readFileFromShards}, but fetches the manifest from a space first. */
+    async readFile(spaceId, fileId) {
+        const space = this.requireSpace("readFile");
+        const manifest = await space.readFileManifest(spaceId, fileId);
+        return await this.readFileFromShards(manifest);
+    }
+    /**
+     * Delete the manifest from a space. **Does not GC the shards** — those
+     * are content-addressed and may be referenced by other manifests.
+     * Garbage collection is a separate server-side concern (Phase D / D-ish).
+     */
+    async deleteFile(spaceId, fileId) {
+        const space = this.requireSpace("deleteFile");
+        return space.deleteFileManifest(spaceId, fileId);
+    }
+    /** Convenience pass-through. */
+    async listFiles(spaceId) {
+        const space = this.requireSpace("listFiles");
+        return space.listFiles(spaceId);
+    }
+    /** Read a manifest verbatim — useful for "share file" / export flows. */
+    async readManifest(spaceId, fileId) {
+        const space = this.requireSpace("readManifest");
+        return space.readFileManifest(spaceId, fileId);
+    }
+    // -------------------------------------------------------------------------
+    // Internals
+    // -------------------------------------------------------------------------
+    requireSpace(operation) {
+        if (!this.space) {
+            throw new Error(`FileStorage.${operation}: a SharedSpaceClient is required for this operation ` +
+                "(constructor was called without `space`)");
+        }
+        return this.space;
+    }
+    /** Encrypt + encode + upload one chunk; return its manifest entry. */
+    async writeChunk(plaintext, chunkIndex) {
+        const keyMaterial = this.cipher.generateKeyMaterial();
+        const ciphertext = plaintext.length === 0
+            ? new Uint8Array(0)
+            : await this.cipher.encryptChunk(plaintext, keyMaterial);
+        // An empty chunk encodes to nothing — emit a manifest entry with no
+        // shards so the reader can re-emit an empty plaintext and skip the
+        // shard round-trip.
+        if (ciphertext.length === 0) {
+            return {
+                id: generateId(),
+                chunkIndex,
+                originalSize: 0,
+                ciphertextSize: 0,
+                dataShards: this.dataShards,
+                parityShards: this.parityShards,
+                shardSize: 0,
+                shardHashes: [],
+                cipher: keyMaterial,
+            };
+        }
+        const encoded = this.codec.encode(ciphertext, this.dataShards, this.parityShards);
+        const hashes = await Promise.all(encoded.shards.map((s) => shardHash(s)));
+        await this.runWithConcurrency(encoded.shards.map((bytes, i) => async () => {
+            await this.shards.putShard(hashes[i], bytes);
+        }));
+        return {
+            id: generateId(),
+            chunkIndex,
+            originalSize: plaintext.length,
+            ciphertextSize: ciphertext.length,
+            dataShards: encoded.dataShards,
+            parityShards: encoded.parityShards,
+            shardSize: encoded.shardSize,
+            shardHashes: hashes,
+            cipher: keyMaterial,
+        };
+    }
+    /** Inverse of `writeChunk`. */
+    async readChunk(manifest) {
+        if (manifest.shardHashes.length === 0) {
+            // Empty chunk fast path.
+            return new Uint8Array(0);
+        }
+        // Fetch shards in parallel. Anything missing becomes a placeholder so
+        // the decoder can fill it in from the parity shards (up to
+        // `parityShards` allowed).
+        const fetched = new Array(manifest.shardHashes.length);
+        await this.runWithConcurrency(manifest.shardHashes.map((hash, i) => async () => {
+            fetched[i] = await this.shards.getShard(hash);
+        }));
+        const deadIndexes = [];
+        const shards = fetched.map((bytes, i) => {
+            if (bytes === null) {
+                deadIndexes.push(i);
+                return new Uint8Array(manifest.shardSize);
+            }
+            if (bytes.length !== manifest.shardSize) {
+                throw new Error(`FileStorage: shard ${manifest.shardHashes[i]} has wrong size ` +
+                    `(got ${bytes.length}, expected ${manifest.shardSize})`);
+            }
+            return bytes;
+        });
+        if (deadIndexes.length > manifest.parityShards) {
+            throw new Error(`FileStorage: chunk ${manifest.id} unrecoverable — ${deadIndexes.length} shards missing, ` +
+                `only ${manifest.parityShards} tolerated`);
+        }
+        const ciphertextPadded = this.codec.decode(shards, manifest.parityShards, deadIndexes, manifest.ciphertextSize);
+        return await this.cipher.decryptChunk(ciphertextPadded, manifest.cipher);
+    }
+    /** Run `tasks` with at most `this.concurrency` in flight. */
+    async runWithConcurrency(tasks) {
+        let cursor = 0;
+        const concurrency = this.concurrency;
+        async function nextWorker() {
+            while (cursor < tasks.length) {
+                const idx = cursor++;
+                await tasks[idx]();
+            }
+        }
+        const workers = new Array(Math.min(concurrency, tasks.length))
+            .fill(null)
+            .map(() => nextWorker());
+        await Promise.all(workers);
+    }
 }
-/**
- * The wbindgen import object — every callback Rust expects from JS. Names are
- * hard-coded by wasm-bindgen based on the Rust function signatures; do not
- * rename. If the upstream package is regenerated, these may drift and need
- * resyncing with the new `wasm_reed_solomon_erasure.js`.
- */
-function buildImports() {
-    const wbindgen = {
-        __wbindgen_object_drop_ref: (arg0) => {
-            takeObject(arg0);
-        },
-        __wbg_buffer_7af23f65f6c64548: (arg0) => {
-            const ret = getObject(arg0).buffer;
-            return addHeapObject(ret);
-        },
-        __wbg_newwithbyteoffsetandlength_ce1e75f0ce5f7974: (arg0, arg1, arg2) => {
-            const ret = new Uint8Array(getObject(arg0), arg1 >>> 0, arg2 >>> 0);
-            return addHeapObject(ret);
-        },
-        __wbg_new_cc9018bd6f283b6f: (arg0) => {
-            const ret = new Uint8Array(getObject(arg0));
-            return addHeapObject(ret);
-        },
-        __wbg_set_f25e869e4565d2a2: (arg0, arg1, arg2) => {
-            getObject(arg0).set(getObject(arg1), arg2 >>> 0);
-        },
-        __wbg_length_0acb1cf9bbaf8519: (arg0) => {
-            return getObject(arg0).length;
-        },
-        __wbg_new_e8c5277c0f9e2cfc: (arg0) => {
-            const ret = new Uint32Array(getObject(arg0));
-            return addHeapObject(ret);
-        },
-        __wbg_set_03c7d8c063f469ef: (arg0, arg1, arg2) => {
-            getObject(arg0).set(getObject(arg1), arg2 >>> 0);
-        },
-        __wbg_length_f98ca60981480796: (arg0) => {
-            return getObject(arg0).length;
-        },
-        __wbindgen_throw: (arg0, arg1) => {
-            throw new Error(getStringFromWasm(arg0, arg1));
-        },
-        __wbindgen_memory: () => {
-            return addHeapObject(wasm.memory);
-        },
-    };
-    return { __wbindgen_placeholder__: wbindgen };
+/** 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);
 }
-let _readyPromise = null;
+
 /**
- * Load and instantiate the WASM module. Idempotent — repeated calls await the
- * same one-shot promise.
- *
- * Two ways to initialize, matching the pattern used by `workers/groth16-verifier`:
- *   1. `await initRsWasm()` — uses the bundled .wasm (base64-inlined at build
- *      time by `@rollup/plugin-wasm`). Works in any runtime that allows
- *      runtime `WebAssembly.compile()`.
- *   2. `await initRsWasm(myWasmModule)` — accepts a pre-compiled
- *      `WebAssembly.Module`. Useful when the bundled loader path isn't
- *      available (vitest, CF Workers wanting deploy-time precompile, etc.).
+ * 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 }
  */
-async function initRsWasm(wasmModule) {
-    if (_readyPromise)
-        return _readyPromise;
-    _readyPromise = (async () => {
-        const imports = buildImports();
-        let instance;
-        if (wasmModule) {
-            // `instantiate(module, imports)` returns a bare Instance.
-            instance = await WebAssembly.instantiate(wasmModule, imports);
+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.");
         }
-        else {
-            // Defer the `.wasm` import to a separate module so vitest can load
-            // `rs.ts` without it. Production callers either don't pass a
-            // module (and hit the bundled loader here) or pass one explicitly.
-            const bundled = (await Promise.resolve().then(function () { return bundledLoader; })).default;
-            const result = await bundled(imports);
-            // The bundled loader's actual return type is
-            // `{ module: WebAssembly.Module, instance: WebAssembly.Instance }`
-            // — the rollup-plugin-wasm shape from `WebAssembly.instantiate(buffer, imports)`.
-            // Older versions (or future changes) may return a bare Instance,
-            // so accept either shape.
-            instance = unwrapInstance(result);
+        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);
         }
-        wasm = instance.exports;
-    })();
-    return _readyPromise;
+        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;
+}
+
 /**
- * Normalize the value returned by `WebAssembly.instantiate` / the
- * rollup-plugin-wasm loader into a bare `WebAssembly.Instance`. Handles
- * both the `(module, imports)` overload (returns Instance) and the
- * `(buffer, imports)` overload (returns `{ module, instance }`).
+ * `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.
  */
-function unwrapInstance(result) {
-    if (result && typeof result === "object") {
-        const candidate = result;
-        if (candidate.instance && typeof candidate.instance === "object" && "exports" in candidate.instance) {
-            return candidate.instance;
+/** 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).");
         }
-        if ("exports" in candidate) {
-            return result;
+        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 };
     }
-    throw new Error("rs.ts: bundled WASM loader returned an unrecognized shape — expected WebAssembly.Instance or { module, instance }");
-}
-function ensureReady() {
-    if (!wasm) {
-        throw new Error("rs.ts: WASM not initialized. Call `await initRsWasm()` first.");
+    /** Read a file from its space (resolves the manifest, then the shards). */
+    async readFile(spaceId, fileId) {
+        return this.fs().readFile(spaceId, fileId);
     }
-}
-// ---------------------------------------------------------------------------
-// Public API — encode + reconstruct
-// ---------------------------------------------------------------------------
-/**
- * Encode the input data shards with `parityShard` parity shards. All input
- * shards must be Uint8Arrays of equal length; output contains the input shards
- * unchanged plus `parityShard` newly computed parity shards.
- */
-function encode(dataShards, parityShard) {
-    ensureReady();
-    const w = wasm;
-    try {
-        const retptr = w.__wbindgen_add_to_stack_pointer(-16);
-        const ptr0 = passArrayJsValueToWasm(dataShards, w.__wbindgen_malloc);
-        const len0 = WASM_VECTOR_LEN;
-        w.encode(retptr, ptr0, len0, parityShard);
-        const r0 = i32()[retptr / 4 + 0];
-        const r1 = i32()[retptr / 4 + 1];
-        const v1 = getArrayJsValueFromWasm(r0, r1).slice();
-        w.__wbindgen_free(r0, r1 * 4);
-        return v1;
+    /**
+     * 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);
     }
-    finally {
-        w.__wbindgen_add_to_stack_pointer(16);
+    /**
+     * 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;
     }
-}
-/**
- * Reconstruct the original full shard array. `corruptedShards` is the full
- * list (data + parity) with placeholder Uint8Arrays at positions listed in
- * `deadShardIndexes`. Returns the recovered, complete list of shards.
- *
- * Up to `parityShard` shards may be missing; more than that is uncorrectable
- * and the underlying WASM throws.
- */
-function reconstruct(corruptedShards, parityShard, deadShardIndexes) {
-    ensureReady();
-    const w = wasm;
-    try {
-        const retptr = w.__wbindgen_add_to_stack_pointer(-16);
-        const ptr0 = passArrayJsValueToWasm(corruptedShards, w.__wbindgen_malloc);
-        const len0 = WASM_VECTOR_LEN;
-        w.reconstruct(retptr, ptr0, len0, parityShard, addHeapObject(deadShardIndexes));
-        const r0 = i32()[retptr / 4 + 0];
-        const r1 = i32()[retptr / 4 + 1];
-        const v1 = getArrayJsValueFromWasm(r0, r1).slice();
-        w.__wbindgen_free(r0, r1 * 4);
-        return v1;
+    /** Read a manifest verbatim (e.g. to share a file). */
+    async getManifest(spaceId, fileId) {
+        return this.fs().readManifest(spaceId, fileId);
     }
-    finally {
-        w.__wbindgen_add_to_stack_pointer(16);
+    // -------------------------------------------------------------------------
+    // 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;
     }
 }
 
 /**
- * Reed–Solomon erasure-coding codec.
- *
- * Wraps the WASM-backed `encode` / `reconstruct` primitives in `wasm/rs.ts`
- * with shard-padding bookkeeping so callers can hand it any-length input and
- * get back uniform-size shards.
- *
- * Usage:
- *   const codec = new ReedSolomonCodec();
- *   await codec.ready();
- *   const { shards, shardSize, originalSize } = codec.encode(plaintext, 4, 2);
- *   // 6 shards (4 data + 2 parity), each `shardSize` bytes
- *   // …ship them, lose up to 2, then …
- *   const recovered = codec.decode(shards, 2, deadIndexes, originalSize);
+ * 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.
  *
- * Why the explicit `originalSize`: RS pads input to make every data shard the
- * same length. The decoder must trim that padding back off after recovery.
- * The caller is responsible for stashing `originalSize` somewhere durable
- * (the file manifest, in this codebase).
+ * 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.
  */
-class ReedSolomonCodec {
+// ---------------------------------------------------------------------------
+// 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;
+    }
     /**
-     * Resolves once the WASM module is loaded; safe to call repeatedly.
-     *
-     * Pass `wasmModule` to use a pre-compiled module (e.g. in tests where the
-     * rollup-inlined loader path isn't available, or in CF Workers where you
-     * want to load the module at deploy time). Default path uses the bundled
-     * base64-inlined wasm — works in Node, browsers, and Workers.
+     * Generate this client's ECDH + ECDSA keypair (idempotent — safe to call
+     * multiple times across reconnects; only the first call generates).
      */
-    ready(wasmModule) {
-        return initRsWasm(wasmModule);
+    async initialize() {
+        if (this._initialized)
+            return;
+        if (!this.keyStore.getKeyPair(this.myId)) {
+            await this.keyStore.generateOwnKeyPair(this.myId);
+        }
+        this._initialized = true;
+        this._resolveReady();
     }
     /**
-     * Split `data` into `dataShards` equal-size chunks (zero-padded to fit),
-     * compute `parityShards` parity shards, and return all of them.
+     * 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))).
      */
-    encode(data, dataShards, parityShards) {
-        if (dataShards < 1)
-            throw new Error("ReedSolomonCodec.encode: dataShards must be >= 1");
-        if (parityShards < 1)
-            throw new Error("ReedSolomonCodec.encode: parityShards must be >= 1");
-        if (data.length === 0)
-            throw new Error("ReedSolomonCodec.encode: data is empty");
-        // The wbindgen-generated WASM in `wasm-reed-solomon-erasure@0.2.2` takes
-        // the `parity_shard` count separately and infers `total = data.length +
-        // parity_shard`. Every shard must be the same length, so we pad the
-        // input to `dataShards * shardSize` with trailing zeros.
-        const shardSize = Math.ceil(data.length / dataShards);
-        const splitInputs = [];
-        for (let i = 0; i < dataShards; i++) {
-            // Each shard is its own backing ArrayBuffer so the WASM side
-            // doesn't observe overlapping views (which would confuse the
-            // wbindgen length lookups).
-            const shard = new Uint8Array(shardSize);
-            const start = i * shardSize;
-            const end = Math.min(start + shardSize, data.length);
-            if (start < data.length) {
-                shard.set(data.subarray(start, end));
-            }
-            splitInputs.push(shard);
+    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");
         }
-        const shards = encode(splitInputs, parityShards);
-        // The underlying call returns N+M shards; first N are the (padded)
-        // data shards we just sent in, last M are the parity shards.
         return {
-            shards,
-            shardSize,
-            originalSize: data.length,
-            dataShards,
-            parityShards,
+            keyExchange: {
+                type: "handshake",
+                userId: this.myId,
+                ecdhPublicKey: await exportJwkBase64(ownEcdh.publicKey),
+                ecdsaPublicKey: await exportJwkBase64(ownEcdsa.publicKey),
+            },
         };
     }
     /**
-     * Reconstruct the original `data` from `shards`. Up to `parityShards`
-     * shards may be missing; for each missing shard, pass an empty
-     * `Uint8Array` placeholder at its position and list the position in
-     * `deadShardIndexes`.
+     * 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.
      *
-     * `originalSize` is required so the trailing zero-padding can be trimmed.
+     * 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).
      */
-    decode(shards, parityShards, deadShardIndexes, originalSize) {
-        if (parityShards < 1)
-            throw new Error("ReedSolomonCodec.decode: parityShards must be >= 1");
-        if (shards.length <= parityShards) {
-            throw new Error("ReedSolomonCodec.decode: shards.length must be > parityShards");
-        }
-        if (deadShardIndexes.length > parityShards) {
-            throw new Error(`ReedSolomonCodec.decode: too many missing shards (${deadShardIndexes.length} > ${parityShards})`);
-        }
-        const dataShards = shards.length - parityShards;
-        const recovered = deadShardIndexes.length === 0
-            ? shards
-            : reconstruct(shards, parityShards, new Uint32Array(deadShardIndexes));
-        // Concatenate the leading `dataShards`, then trim padding back off.
-        const shardSize = recovered[0]?.length ?? 0;
-        const out = new Uint8Array(dataShards * shardSize);
-        for (let i = 0; i < dataShards; i++) {
-            out.set(recovered[i], i * shardSize);
+    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 out.subarray(0, originalSize);
-    }
-}
-
-/**
- * HTTP client for the open content-addressed shard store.
- *
- * Each shard is named by the lowercase hex SHA-256 of its ciphertext bytes.
- * The server verifies the hash on PUT, so the address authenticates the
- * contents — there's no benefit to ACLing PUT/GET, and making them open
- * enables cross-user dedup down the line.
- *
- * Wire protocol:
- *   PUT  /api/shards/:hash    body: shard bytes (application/octet-stream)
- *                             200 { ok: true, hash, size, dedup: boolean }
- *                             400 if hash doesn't match body
- *
- *   GET  /api/shards/:hash    200 with shard bytes (application/octet-stream)
- *                             404 if absent
- *
- *   HEAD /api/shards/:hash    200 if present (no body) — used by callers to
- *                             skip a PUT they'd otherwise dedup-rewrite. The
- *                             server can ignore the optimization if it wants.
- */
-/**
- * Compute the lowercase hex SHA-256 of `bytes`. Available via WebCrypto in
- * every runtime this SDK targets.
- */
-async function shardHash(bytes) {
-    const subtle = globalThis.crypto?.subtle;
-    if (!subtle) {
-        throw new Error("shardHash: `globalThis.crypto.subtle` is unavailable in this runtime.");
+        return frames;
     }
-    const digest = await subtle.digest("SHA-256", bytes);
-    return toHex(new Uint8Array(digest));
-}
-class ShardClient {
-    baseUrl;
-    pathPrefix;
-    fetchFn;
-    constructor(opts) {
-        if (!opts?.baseUrl)
-            throw new Error("ShardClient: `baseUrl` is required");
-        // Strip trailing slash so url concatenation stays clean.
-        this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
-        // Normalize prefix to leading-slash + no-trailing-slash form so the
-        // URL builder can blindly append `/{hash}`.
-        const rawPrefix = opts.pathPrefix ?? "/api/shards";
-        const withSlash = rawPrefix.startsWith("/") ? rawPrefix : `/${rawPrefix}`;
-        this.pathPrefix = withSlash.replace(/\/+$/, "");
-        const f = opts.fetch ?? globalThis.fetch;
-        if (typeof f !== "function") {
-            throw new Error("ShardClient: `globalThis.fetch` is unavailable; pass an explicit fetch.");
+    /**
+     * 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 };
         }
-        this.fetchFn = f.bind(globalThis);
+        return { kind: "ignored", reason: "unknown frame type" };
     }
-    /** Build the URL for a given shard hash — exposed for callers that want to log or pre-resolve. */
-    urlForHash(hash) {
-        return `${this.baseUrl}${this.pathPrefix}/${encodeURIComponent(hash)}`;
+    // -- introspection ---------------------------------------------------------
+    /** List of peer ids we have an established ratchet for. */
+    peers() {
+        return Array.from(this.ratchets.keys());
     }
-    /**
-     * Upload a shard. The server verifies SHA-256(body) matches `:hash` and
-     * rejects with 400 if not, so the caller is the source of truth on
-     * naming. Re-uploading an existing shard is idempotent — the server
-     * returns `dedup: true` in that case.
-     */
-    async putShard(hash, bytes) {
-        const url = this.urlForHash(hash);
-        const response = await this.fetchFn(url, {
-            method: "PUT",
-            headers: { "content-type": "application/octet-stream" },
-            // BufferSource is what fetch's body expects; a Uint8Array satisfies it.
-            body: bytes,
-        });
-        if (!response.ok) {
-            const text = await safeText(response);
-            throw new Error(`ShardClient.putShard(${hash}) failed (${response.status}): ${text}`);
-        }
-        let dedup = false;
-        try {
-            const json = (await response.json());
-            dedup = Boolean(json?.dedup);
-        }
-        catch {
-            // Server returned 200 with no body — treat as fresh upload.
-        }
-        return { dedup };
+    /** Has the handshake completed for this peer? */
+    hasRatchetFor(peerId) {
+        return this.ratchets.has(peerId);
     }
     /**
-     * Fetch a shard by hash. Throws if the server returns a non-200; returns
-     * `null` for 404 so callers can distinguish "missing" from "errored".
+     * 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.
      */
-    async getShard(hash) {
-        const url = this.urlForHash(hash);
-        const response = await this.fetchFn(url, { method: "GET" });
-        if (response.status === 404)
-            return null;
-        if (!response.ok) {
-            const text = await safeText(response);
-            throw new Error(`ShardClient.getShard(${hash}) failed (${response.status}): ${text}`);
-        }
-        const buf = await response.arrayBuffer();
-        return new Uint8Array(buf);
+    forgetPeer(peerId) {
+        this.ratchets.delete(peerId);
+        this.sentHandshakeTo.delete(peerId);
     }
-    /**
-     * Check whether a shard exists. Lets the caller skip a PUT they'd otherwise
-     * dedup-rewrite. The server can implement this as a HEAD or return a small
-     * JSON body — we don't depend on either.
-     */
-    async hasShard(hash) {
-        const url = this.urlForHash(hash);
-        const response = await this.fetchFn(url, { method: "HEAD" });
-        return response.status === 200;
+    // -- internals -------------------------------------------------------------
+    /** Deterministic per-pair session id — same string on both sides. */
+    _sessionIdFor(peerId) {
+        return [this.myId, peerId].sort().join(":");
     }
 }
-async function safeText(response) {
-    try {
-        return await response.text();
-    }
-    catch {
-        return "";
-    }
+// ---------------------------------------------------------------------------
+// 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);
 }
 
 /**
- * `FileStorage` — top-level entry point for chunked, encrypted, erasure-coded
- * file storage.
+ * BroadcastChannel — a turnkey end-to-end encrypted channel for multi-peer
+ * "room"-style apps (e.g. a chat). Wires together:
  *
- * Pipeline for writing a file:
- *   1. Split the plaintext into fixed-size chunks (default 4 MiB).
- *   2. For each chunk:
- *        a. Generate a fresh AES-256-GCM key + 12-byte IV (`ChunkCipher`).
- *        b. Encrypt the chunk → ciphertext (plaintext.length + 16 bytes tag).
- *        c. Reed–Solomon encode the ciphertext into `dataShards + parityShards`
- *           equal-length shards (`ReedSolomonCodec`).
- *        d. PUT every shard to the content-addressed shard store, keyed by
- *           SHA-256 of the shard bytes (`ShardClient`).
- *   3. Build a `FileManifest` listing every chunk's keys, IVs, sizes, and
- *      the SHA-256 of every shard in order.
+ *   - `WSTransport` for socket lifecycle, reconnect, and offline frame queue
+ *   - `EncryptedSession` for per-peer Double Ratchet state, handshake
+ *     reciprocation, fan-out encryption, and recipient filtering
  *
- * Two ways to use the manifest:
- *   - {@link FileStorage.writeFileToShards} returns it to the caller, who is
- *     then responsible for delivering it to readers (e.g. by E2E-encrypting
- *     it as a chat message). The chat application takes this path.
- *   - {@link FileStorage.writeFile} additionally POSTs the manifest to a
- *     gated multi-user space (`SharedSpaceClient`) so any participant of the
- *     space can read the file by manifest id later.
+ * The host app only deals with high-level events and method calls; it never
+ * touches `new WebSocket(...)` or builds cipherMessage frames by hand.
  *
- * Reading is the inverse: {@link FileStorage.readFileFromShards} takes a
- * manifest and reassembles the plaintext; {@link FileStorage.readFile} first
- * fetches the manifest from the space.
+ * 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.
  */
-class FileStorage {
-    space;
-    shards;
-    chunkSize;
-    dataShards;
-    parityShards;
-    concurrency;
-    cipher = new ChunkCipher();
-    codec = new ReedSolomonCodec();
-    rsWasmModule;
+// ---------------------------------------------------------------------------
+// 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?.shards)
-            throw new Error("FileStorage: `shards` (ShardClient) is required");
-        this.space = opts.space;
-        this.shards = opts.shards;
-        this.chunkSize = opts.chunkSize ?? 4 * 1024 * 1024;
-        this.dataShards = opts.dataShards ?? 4;
-        this.parityShards = opts.parityShards ?? 2;
-        this.concurrency = Math.max(1, opts.concurrency ?? 8);
-        this.rsWasmModule = opts.rsWasmModule;
-        if (this.chunkSize < 1)
-            throw new Error("FileStorage: chunkSize must be >= 1 byte");
-        if (this.dataShards < 1)
-            throw new Error("FileStorage: dataShards must be >= 1");
-        if (this.parityShards < 1)
-            throw new Error("FileStorage: parityShards must be >= 1");
+        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();
     }
-    // -------------------------------------------------------------------------
-    // Shard-only pipeline — the caller owns the manifest. Used by chat file
-    // sharing, where the manifest rides as an E2E-encrypted chat message.
-    // -------------------------------------------------------------------------
     /**
-     * Chunk → encrypt → encode → upload-shards. Returns the resulting manifest
-     * along with a `FileStat` summary. The caller is responsible for storing
-     * or transmitting the manifest however it likes.
+     * 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 writeFileToShards(input) {
-        await this.codec.ready(this.rsWasmModule);
-        const data = await toUint8Array(input.data);
-        const fileId = input.fileId ?? generateId();
-        const createdAt = Date.now();
-        const chunks = [];
-        // 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
-        // `this.concurrency`.
-        for (let chunkIndex = 0; chunkIndex * this.chunkSize < Math.max(1, data.length); chunkIndex++) {
-            const start = chunkIndex * this.chunkSize;
-            const end = Math.min(start + this.chunkSize, data.length);
-            const plaintext = data.subarray(start, end);
-            chunks.push(await this.writeChunk(plaintext, chunkIndex));
-            // 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)
-                break;
-        }
-        const manifest = {
-            id: fileId,
-            name: input.metadata.name,
-            size: data.length,
-            type: input.metadata.type,
-            path: input.metadata.path,
-            lastModified: input.metadata.lastModified ?? createdAt,
-            createdAt,
-            chunks,
-            version: 1,
-        };
-        return { manifest, stat: manifestToStat(manifest) };
+    async announce() {
+        if (this.announced)
+            return;
+        this.announced = true;
+        const frame = await this.session.getOwnKeyExchange();
+        this.transport.send(JSON.stringify(frame));
     }
     /**
-     * Inverse of {@link writeFileToShards}. Takes a manifest the caller
-     * obtained somehow (chat message, share link, etc.) and reassembles the
-     * plaintext. Throws if too many shards are missing or any chunk's auth
-     * tag fails.
+     * 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 readFileFromShards(manifest) {
-        await this.codec.ready(this.rsWasmModule);
-        // Materialize each chunk into plaintext, then concatenate. We don't
-        // stream across chunks here because the consuming surface returns
-        // `Uint8Array`; a streaming variant would reuse `readChunk` unchanged.
-        const plaintextChunks = [];
-        for (const chunkManifest of [...manifest.chunks].sort((a, b) => a.chunkIndex - b.chunkIndex)) {
-            plaintextChunks.push(await this.readChunk(chunkManifest));
-        }
-        let total = 0;
-        for (const c of plaintextChunks)
-            total += c.length;
-        const out = new Uint8Array(total);
-        let offset = 0;
-        for (const c of plaintextChunks) {
-            out.set(c, offset);
-            offset += c.length;
+    async send(plaintext) {
+        const frames = await this.session.encrypt(plaintext);
+        for (const frame of frames) {
+            this.transport.send(JSON.stringify(frame));
         }
-        return { data: out, stat: manifestToStat(manifest) };
-    }
-    // -------------------------------------------------------------------------
-    // Space-backed convenience wrappers — encrypt + upload + write manifest.
-    // Require a `SharedSpaceClient` to have been provided at construction.
-    // -------------------------------------------------------------------------
-    /** As {@link writeFileToShards}, plus POSTs the manifest to `input.spaceId`. */
-    async writeFile(input) {
-        const space = this.requireSpace("writeFile");
-        const { manifest, stat } = await this.writeFileToShards(input);
-        await space.writeFileManifest(input.spaceId, manifest);
-        return stat;
-    }
-    /** As {@link readFileFromShards}, but fetches the manifest from a space first. */
-    async readFile(spaceId, fileId) {
-        const space = this.requireSpace("readFile");
-        const manifest = await space.readFileManifest(spaceId, fileId);
-        return await this.readFileFromShards(manifest);
+        return frames.length;
     }
     /**
-     * Delete the manifest from a space. **Does not GC the shards** — those
-     * are content-addressed and may be referenced by other manifests.
-     * Garbage collection is a separate server-side concern (Phase D / D-ish).
+     * 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}`).
      */
-    async deleteFile(spaceId, fileId) {
-        const space = this.requireSpace("deleteFile");
-        return space.deleteFileManifest(spaceId, fileId);
-    }
-    /** Convenience pass-through. */
-    async listFiles(spaceId) {
-        const space = this.requireSpace("listFiles");
-        return space.listFiles(spaceId);
+    sendRaw(frame) {
+        this.transport.send(JSON.stringify(frame));
     }
-    /** Read a manifest verbatim — useful for "share file" / export flows. */
-    async readManifest(spaceId, fileId) {
-        const space = this.requireSpace("readManifest");
-        return space.readFileManifest(spaceId, fileId);
+    // -- introspection ---------------------------------------------------------
+    /** List of peer ids we have an established ratchet for. */
+    peers() {
+        return this.session.peers();
     }
-    // -------------------------------------------------------------------------
-    // Internals
-    // -------------------------------------------------------------------------
-    requireSpace(operation) {
-        if (!this.space) {
-            throw new Error(`FileStorage.${operation}: a SharedSpaceClient is required for this operation ` +
-                "(constructor was called without `space`)");
-        }
-        return this.space;
+    /** Drop a peer's ratchet (e.g. when they leave the room). */
+    forgetPeer(peerId) {
+        this.session.forgetPeer(peerId);
     }
-    /** Encrypt + encode + upload one chunk; return its manifest entry. */
-    async writeChunk(plaintext, chunkIndex) {
-        const keyMaterial = this.cipher.generateKeyMaterial();
-        const ciphertext = plaintext.length === 0
-            ? new Uint8Array(0)
-            : await this.cipher.encryptChunk(plaintext, keyMaterial);
-        // An empty chunk encodes to nothing — emit a manifest entry with no
-        // shards so the reader can re-emit an empty plaintext and skip the
-        // shard round-trip.
-        if (ciphertext.length === 0) {
-            return {
-                id: generateId(),
-                chunkIndex,
-                originalSize: 0,
-                ciphertextSize: 0,
-                dataShards: this.dataShards,
-                parityShards: this.parityShards,
-                shardSize: 0,
-                shardHashes: [],
-                cipher: keyMaterial,
-            };
-        }
-        const encoded = this.codec.encode(ciphertext, this.dataShards, this.parityShards);
-        const hashes = await Promise.all(encoded.shards.map((s) => shardHash(s)));
-        await this.runWithConcurrency(encoded.shards.map((bytes, i) => async () => {
-            await this.shards.putShard(hashes[i], bytes);
-        }));
-        return {
-            id: generateId(),
-            chunkIndex,
-            originalSize: plaintext.length,
-            ciphertextSize: ciphertext.length,
-            dataShards: encoded.dataShards,
-            parityShards: encoded.parityShards,
-            shardSize: encoded.shardSize,
-            shardHashes: hashes,
-            cipher: keyMaterial,
-        };
+    isConnected() {
+        return this.transport.isConnected();
     }
-    /** Inverse of `writeChunk`. */
-    async readChunk(manifest) {
-        if (manifest.shardHashes.length === 0) {
-            // Empty chunk fast path.
-            return new Uint8Array(0);
+    // -- internals -------------------------------------------------------------
+    async handleInboundFrame(raw) {
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
         }
-        // Fetch shards in parallel. Anything missing becomes a placeholder so
-        // the decoder can fill it in from the parity shards (up to
-        // `parityShards` allowed).
-        const fetched = new Array(manifest.shardHashes.length);
-        await this.runWithConcurrency(manifest.shardHashes.map((hash, i) => async () => {
-            fetched[i] = await this.shards.getShard(hash);
-        }));
-        const deadIndexes = [];
-        const shards = fetched.map((bytes, i) => {
-            if (bytes === null) {
-                deadIndexes.push(i);
-                return new Uint8Array(manifest.shardSize);
-            }
-            if (bytes.length !== manifest.shardSize) {
-                throw new Error(`FileStorage: shard ${manifest.shardHashes[i]} has wrong size ` +
-                    `(got ${bytes.length}, expected ${manifest.shardSize})`);
-            }
-            return bytes;
-        });
-        if (deadIndexes.length > manifest.parityShards) {
-            throw new Error(`FileStorage: chunk ${manifest.id} unrecoverable — ${deadIndexes.length} shards missing, ` +
-                `only ${manifest.parityShards} tolerated`);
+        catch (err) {
+            this.emit(BroadcastChannelEvents.ERROR, err);
+            return;
         }
-        const ciphertextPadded = this.codec.decode(shards, manifest.parityShards, deadIndexes, manifest.ciphertextSize);
-        return await this.cipher.decryptChunk(ciphertextPadded, manifest.cipher);
-    }
-    /** Run `tasks` with at most `this.concurrency` in flight. */
-    async runWithConcurrency(tasks) {
-        let cursor = 0;
-        const concurrency = this.concurrency;
-        async function nextWorker() {
-            while (cursor < tasks.length) {
-                const idx = cursor++;
-                await tasks[idx]();
+        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;
         }
-        const workers = new Array(Math.min(concurrency, tasks.length))
-            .fill(null)
-            .map(() => nextWorker());
-        await Promise.all(workers);
+        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.
@@ -4791,6 +5194,46 @@ async function importEcdhPublicKey(encoded) {
 }
 /** The space's id is just its encoded ECDH public key. */
 const encodeSpaceId = exportEcdhPublicKey;
+// ---------------------------------------------------------------------------
+// Sender authentication (ECDSA P-384, matching the Double Ratchet path).
+// A fan-out message is signed by its sender's identity ECDSA key so receivers
+// can verify authorship end-to-end — independent of the relay, which only
+// stamps `source` server-side. SHA-256 hash to match `DoubleRatchet`.
+// ---------------------------------------------------------------------------
+const ECDSA_PARAMS = { name: "ECDSA", namedCurve: "P-384" };
+const ECDSA_SIGN = { name: "ECDSA", hash: "SHA-256" };
+/** Encode an ECDSA public `CryptoKey` as a base64url JWK string. */
+async function exportEcdsaPublicKey(key) {
+    const jwk = await getSubtle().exportKey("jwk", key);
+    return toBase64Url(utf8Encode(JSON.stringify(jwk)));
+}
+/** Decode a base64url JWK string back into an ECDSA verify-only public key. */
+async function importEcdsaPublicKey(encoded) {
+    const jwk = JSON.parse(utf8Decode(fromBase64Url(encoded)));
+    return getSubtle().importKey("jwk", jwk, ECDSA_PARAMS, true, ["verify"]);
+}
+/**
+ * Canonical bytes a sender signs (and a receiver re-derives). Binds the claimed
+ * sender + routing + the sealed ciphertext, so a relay can't relabel `source`
+ * and a member can't reuse another's ciphertext under a new envelope.
+ */
+function canonicalMessage(fields) {
+    return [fields.source, fields.target, fields.subject, fields.epoch, fields.iv, fields.ciphertext].join("\n");
+}
+/** Sign the canonical bytes with the sender's ECDSA identity private key. */
+async function signSpaceMessage(canonical, ecdsaPriv) {
+    const sig = await getSubtle().sign(ECDSA_SIGN, ecdsaPriv, utf8Encode(canonical));
+    return toBase64(new Uint8Array(sig));
+}
+/** Verify a signature over the canonical bytes against the sender's ECDSA key. */
+async function verifySpaceMessage(canonical, sigB64, ecdsaPub) {
+    try {
+        return await getSubtle().verify(ECDSA_SIGN, ecdsaPub, fromBase64(sigB64), utf8Encode(canonical));
+    }
+    catch {
+        return false;
+    }
+}
 /** Generate a fresh space identity keypair (P-384 ECDH). */
 async function generateSpaceIdentity() {
     const kp = await getSubtle().generateKey(ECDH_PARAMS, true, ["deriveBits"]);
@@ -5016,16 +5459,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 packet = new Packet({
-            subject: opts.channel ?? "default",
-            source: this.deps.myId(),
-            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) {
@@ -5033,6 +5467,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);
@@ -5056,6 +5540,9 @@ class Space {
         if (!res.ok)
             throw new Error(`Space.history: ${res.status} ${res.statusText}`);
         const body = (await res.json());
+        // Warm the member directory once so historical senders' signatures verify.
+        // (refreshDirectory swallows its own transport errors.)
+        await this.deps.keyring?.refreshDirectory();
         const messages = [];
         for (const raw of body.messages ?? []) {
             const decoded = await this.decodeFrame(raw, cipher);
@@ -5091,6 +5578,9 @@ class Space {
         const keyring = this.requireKeyring();
         await keyring.bootstrapNew();
         await this.connect();
+        // Publish our identity in the member directory so peers can verify our
+        // message signatures (the creator never "joins", so register here).
+        await keyring.requestKey().catch(() => { });
         // Admit anyone who requested a key before we were listening.
         if (this.deps.autoAdmit !== false) {
             await keyring.admitPending().catch(() => { });
@@ -5100,6 +5590,10 @@ class Space {
     async admit(memberId, identityEcdhPub) {
         await this.requireKeyring().admit(memberId, identityEcdhPub);
     }
+    /** Invite a user to this (private) channel's membership allowlist. */
+    async invite(username) {
+        await this.requireKeyring().invite(username);
+    }
     /** Rotate to a fresh epoch and re-wrap to the roster (rotate spaces). */
     async rotate(roster) {
         return this.requireKeyring().rotate(roster);
@@ -5112,9 +5606,13 @@ class Space {
         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 });
@@ -5134,15 +5632,45 @@ 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);
-            // Auto-admit: if we hold the group key, wrap it for the newcomer.
+            // A new member appeared — refresh the directory so their future
+            // messages verify, and (if we hold the key) auto-admit them.
+            void this.deps.keyring?.refreshDirectory();
             if (this.deps.autoAdmit !== false && this.deps.keyring?.hasAnyKey() && req.memberId !== this.deps.myId()) {
                 void this.deps.keyring.admit(req.memberId, req.identityEcdhPub).catch(() => { });
             }
@@ -5153,23 +5681,57 @@ 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))
                 return null;
+            // Verify sender authenticity end-to-end: the message must be signed
+            // by `source`'s identity ECDSA key (looked up in the member
+            // directory). Drop anything unsigned, signed by an unknown member,
+            // or whose signature doesn't match — this defeats both member
+            // impersonation and a relay rewriting `source`.
+            if (!(await this.verifySender(packet)))
+                return null;
             const serialized = await cipher.open(packet.headers);
             if (serialized === null)
                 return null; // epoch key we don't hold
@@ -5179,6 +5741,7 @@ class Space {
                 channel: packet.subject,
                 epoch: Number(packet.headers?.epoch ?? 0),
                 contentType: packet.headers?.contentType,
+                handle,
                 message,
             };
         }
@@ -5187,6 +5750,34 @@ class Space {
             return null;
         }
     }
+    /**
+     * True if `packet` carries a valid signature by `source`'s identity key.
+     * On a directory cache miss, refresh once (a new member may have just
+     * joined) before giving up. Without a keyring (legacy handle) there's
+     * nothing to verify against → reject.
+     */
+    async verifySender(packet) {
+        const keyring = this.deps.keyring;
+        const sig = packet.headers?.sig;
+        if (!keyring || typeof sig !== "string")
+            return false;
+        let key = keyring.ecdsaKeyFor(packet.source);
+        if (!key) {
+            await keyring.refreshDirectory();
+            key = keyring.ecdsaKeyFor(packet.source);
+            if (!key)
+                return false;
+        }
+        const canonical = canonicalMessage({
+            source: packet.source,
+            target: packet.target,
+            subject: packet.subject,
+            epoch: Number(packet.headers?.epoch ?? 0),
+            iv: String(packet.headers?.iv ?? ""),
+            ciphertext: String(packet.headers?.ciphertext ?? ""),
+        });
+        return verifySpaceMessage(canonical, sig, key);
+    }
     emitEvent(type, detail) {
         this.events.dispatchEvent(new CustomEvent(type, { detail }));
     }
@@ -5416,10 +6007,37 @@ class SpaceKeyring {
     keys = new Map();
     epoch = 0;
     policy;
+    /** Cached member directory: memberId → imported ECDSA verify key. */
+    memberEcdsa = new Map();
     constructor(deps) {
         this.deps = deps;
         this.policy = deps.historyPolicy ?? "static";
     }
+    // -- member directory (for verifying sender signatures) -------------------
+    /** The cached ECDSA verify key for a member, if known. */
+    ecdsaKeyFor(memberId) {
+        return this.memberEcdsa.get(memberId);
+    }
+    /** Refresh the member directory (memberId → ECDSA key) from the roster. */
+    async refreshDirectory() {
+        let roster;
+        try {
+            roster = await this.deps.transport.fetchRoster();
+        }
+        catch {
+            return;
+        }
+        for (const m of roster) {
+            if (!m.identityEcdsaPub || this.memberEcdsa.has(m.memberId))
+                continue;
+            try {
+                this.memberEcdsa.set(m.memberId, await importEcdsaPublicKey(m.identityEcdsaPub));
+            }
+            catch {
+                /* skip malformed entries */
+            }
+        }
+    }
     // -- EpochKeyProvider ------------------------------------------------------
     currentEpoch() {
         return this.epoch;
@@ -5473,11 +6091,16 @@ class SpaceKeyring {
         await this.persist();
     }
     // -- newcomer: request + pull ---------------------------------------------
-    /** Post a join request so an online key-holder can wrap a key for us. */
+    /**
+     * Post a join request so an online key-holder can wrap a key for us. Also
+     * publishes our identity keys in the member directory (so others can verify
+     * our message signatures, and the keeper can wrap to us).
+     */
     async requestKey(desiredEpoch) {
         await this.deps.transport.postJoinRequest({
             memberId: this.deps.memberId,
             identityEcdhPub: this.deps.identityEcdhPub,
+            identityEcdsaPub: this.deps.identityEcdsaPub,
             desiredEpoch,
         });
     }
@@ -5563,6 +6186,10 @@ class SpaceKeyring {
         await this.persist();
         return nextEpoch;
     }
+    /** Add `username` to a private channel's membership allowlist (member-only). */
+    async invite(username) {
+        await this.deps.transport.invite(username);
+    }
 }
 
 /**
@@ -5623,6 +6250,9 @@ class KeyringClient {
     async rotate(nextEpoch) {
         return this.post("/keyring/rotate", { nextEpoch });
     }
+    async invite(username) {
+        await this.post("/keyring/invite", { username });
+    }
     async fetchMetadata() {
         try {
             return await this.get("/metadata");
@@ -5679,7 +6309,9 @@ class SpaceNamespace {
         const historyPolicy = opts.historyPolicy ?? "static";
         const identity = await generateSpaceIdentity();
         // Register the space (server records pubkey + policy; the DO is lazy).
-        await this.deps.http.post(`/api/spaces/${encodeURIComponent(identity.id)}/metadata`, { spacePubKey: identity.id, historyPolicy });
+        // For a private space the server also records the creator (this user) as
+        // its first member — so the metadata POST must carry the user session.
+        await this.deps.http.post(`/api/spaces/${encodeURIComponent(identity.id)}/metadata`, { spacePubKey: identity.id, historyPolicy, visibility: opts.private ? "private" : "public" });
         const space = await this.build(identity.id, historyPolicy);
         await space.create();
         return space;
@@ -5727,7 +6359,7 @@ class SpaceNamespace {
         const space = await this.createSpace(opts);
         // Register name → id first so a name clash doesn't leave an admitted keeper.
         try {
-            await this.deps.http.post("/api/app/channels", { name, spaceId: space.id });
+            await this.deps.http.post("/api/app/channels", { name, spaceId: space.id, visibility: opts.private ? "private" : "public" });
         }
         catch (err) {
             if (err instanceof HttpError && err.status === 409) {
@@ -5762,7 +6394,7 @@ class SpaceNamespace {
     // -------------------------------------------------------------------------
     async build(spaceId, historyPolicy) {
         const memberId = this.myId();
-        const identityEcdhPub = await this.ensureIdentity(memberId);
+        const { ecdhPub, ecdsaPub } = await this.ensureIdentity(memberId);
         const transport = new KeyringClient({
             spaceId,
             httpBaseUrl: this.deps.http.baseUrl,
@@ -5771,7 +6403,8 @@ class SpaceNamespace {
         const keyring = new SpaceKeyring({
             spaceId,
             memberId,
-            identityEcdhPub,
+            identityEcdhPub: ecdhPub,
+            identityEcdsaPub: ecdsaPub,
             ownPrivateKey: () => KeyStore.getInstance().getKeyPair(memberId)?.privateKey ?? null,
             transport,
             cache: this.deps.cache,
@@ -5788,14 +6421,15 @@ class SpaceNamespace {
             historyPolicy,
         });
     }
-    /** Ensure the member has an identity ECDH keypair; return its public key. */
+    /** Ensure the member has an identity keypair; return its public ECDH + ECDSA keys. */
     async ensureIdentity(memberId) {
         const store = KeyStore.getInstance();
         if (!store.getKeyPair(memberId)) {
             await store.generateOwnKeyPair(memberId);
         }
-        const pub = store.getKeyPair(memberId).publicKey;
-        return exportEcdhPublicKey(pub);
+        const ecdhPub = await exportEcdhPublicKey(store.getKeyPair(memberId).publicKey);
+        const ecdsaPub = await exportEcdsaPublicKey(store.getAuthKeyPair(memberId).publicKey);
+        return { ecdhPub, ecdsaPub };
     }
     async fetchPolicy(spaceId) {
         const meta = await new KeyringClient({
@@ -5858,7 +6492,9 @@ 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;
@@ -5866,6 +6502,10 @@ class Client {
     space;
     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);
@@ -5877,19 +6517,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,
@@ -5906,6 +6551,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');
@@ -6214,7 +6901,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'));
@@ -6228,21 +6915,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 {
@@ -6298,7 +6985,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) {
@@ -6306,7 +6993,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. */
@@ -6315,7 +7002,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. */
@@ -6324,7 +7011,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 : [];
     }
     // -------------------------------------------------------------------------
@@ -6337,7 +7024,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 = {
@@ -6348,7 +7035,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,
@@ -6360,7 +7047,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
@@ -6381,251 +7068,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.
  *
@@ -6689,5 +7131,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, 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, 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