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

package/dist/browser/index.js

@@ -2383,10 +2383,29 @@ function isCipherFrame(frame) {
  *   - 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;
@@ -2400,16 +2419,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() {
@@ -2427,9 +2458,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);
                 };
@@ -2444,6 +2485,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();
@@ -2462,6 +2504,7 @@ class WSTransport extends EventCore {
             clearTimeout(this.reconnectTimeout);
             this.reconnectTimeout = null;
         }
+        this.stopHeartbeat();
         this.autoReconnect = false;
         if (this.socket) {
             try {
@@ -2492,6 +2535,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) {
@@ -3040,7 +3155,7 @@ function alloc(u32, size) {
  * a convenient way to passphrase-encrypt a payload before putting it.
  */
 let _snarkjs$1 = null;
-async function loadSnarkjs$2() {
+async function loadSnarkjs$1() {
     if (_snarkjs$1)
         return _snarkjs$1;
     _snarkjs$1 = (await import('snarkjs'));
@@ -3054,14 +3169,14 @@ async function loadSnarkjs$2() {
  * Must stay in sync with the `nonce` public-signal width used by both
  * accelerator's `verifyZkAuthProof` and the `preimagePoK` circuit.
  */
-const FIELD_SIZE$2 = 21888242871839275222246405745257275088548364400416034343698204186575808495617n;
+const FIELD_SIZE$1 = 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$2).toString();
+    return (BigInt(hex) % FIELD_SIZE$1).toString();
 }
 /**
  * Read the response body as JSON, falling back to text for the error message
@@ -3163,7 +3278,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 = {
@@ -3174,7 +3289,7 @@ class PersonalSpaceClient {
             salt: this.salt,
             ecdsaPub: this.ecdsaPub,
         };
-        const snarkjs = await loadSnarkjs$2();
+        const snarkjs = await loadSnarkjs$1();
         const { proof, publicSignals } = await snarkjs.groth16.fullProve(input, this.wasmUrl, this.zkeyUrl);
         return {
             challengeId: challenge.challengeId,
@@ -4017,248 +4132,94 @@ async function toUint8Array(data) {
 }
 
 /**
- * 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 }
+ * 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 }
  */
-let snarkjsModule = null;
-async function loadSnarkjs$1() {
-    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$1 = 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. */
+    /** Write a file manifest into the space. Requires space membership. */
     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})`);
+        const url = `${this.filesBase(spaceId)}`;
+        const res = await this.fetchFn(url, this.jsonRequest("POST", { manifest }));
+        await parseOrThrow(res, `writeFileManifest(${manifest.id})`);
     }
-    /** Read a file manifest by id. Requires `read` permission. */
+    /** Read a file manifest by id. Requires space membership. */
     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})`);
+        const url = `${this.filesBase(spaceId)}/${encodeURIComponent(fileId)}`;
+        const res = await this.fetchFn(url, this.jsonRequest("GET"));
+        const data = await parseOrThrow(res, `readFileManifest(${fileId})`);
         return data.manifest;
     }
-    /** Delete a file manifest by id. Requires `delete` permission. */
+    /** Delete a file manifest by id. Requires space membership. */
     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})`);
+        const url = `${this.filesBase(spaceId)}/${encodeURIComponent(fileId)}`;
+        const res = await this.fetchFn(url, this.jsonRequest("DELETE"));
+        const data = await parseOrThrow(res, `deleteFileManifest(${fileId})`);
         return data.existed;
     }
-    /** List file summaries in the space. Requires `read` permission. */
+    /** List file summaries in the space. Requires space membership. */
     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");
+        const url = `${this.filesBase(spaceId)}`;
+        const res = await this.fetchFn(url, this.jsonRequest("GET"));
+        const data = await parseOrThrow(res, "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$1();
-        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");
+    filesBase(spaceId) {
+        return `${this.baseUrl}/api/spaces/${encodeURIComponent(spaceId)}/files`;
     }
     jsonRequest(method, body) {
-        return {
-            method,
-            headers: { "content-type": "application/json" },
-            body: JSON.stringify(body ?? {}),
-        };
+        const init = { method };
+        if (body !== undefined) {
+            init.headers = { "Content-Type": "application/json" };
+            init.body = JSON.stringify(body);
+        }
+        return init;
     }
 }
-function nonceHexToFieldString(nonceHex) {
-    const hex = nonceHex.startsWith("0x") ? nonceHex : "0x" + nonceHex;
-    return (BigInt(hex) % FIELD_SIZE$1).toString();
-}
-async function parseOrThrow(response, label) {
+async function parseOrThrow(response, op) {
+    let parsed = null;
+    try {
+        parsed = await response.json();
+    }
+    catch {
+        // non-JSON body
+    }
     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}`);
+        const msg = parsed && typeof parsed === "object" && "error" in parsed
+            ? String(parsed.error)
+            : `${response.status} ${response.statusText}`;
+        throw new Error(`SharedSpaceClient.${op}: ${msg}`);
     }
-    return (await response.json());
+    return parsed;
 }
 
 /**
@@ -4692,6 +4653,7 @@ class HttpClient {
     baseUrl;
     apiKey;
     getSessionToken;
+    onUnauthorized;
     fetchFn;
     constructor(opts) {
         if (!opts?.baseUrl)
@@ -4699,6 +4661,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`.");
@@ -4731,7 +4694,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) {
@@ -4739,6 +4702,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();
@@ -4968,6 +4940,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({
@@ -5125,14 +5135,14 @@ class StorageCipher {
 }
 
 /**
- * `client.storage` — per-user persistent storage backed by the accelerator's
- * personal space.
+ * `client.kv` — per-user key/value 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
+ *   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
  *
  * 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
@@ -5140,12 +5150,14 @@ class StorageCipher {
  *
  * 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.
+ * 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).
  *
- * `query()` is intentionally deferred — see the SDK overhaul plan.
+ * For **files** (blobs), use `client.storage` instead — `client.kv` is for
+ * small structured values. `query()` is intentionally deferred.
  */
-class StorageNamespace {
+class KvNamespace {
     deps;
     cipher = null;
     cipherIdentity = null;
@@ -5178,7 +5190,7 @@ class StorageNamespace {
     }
     /** 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).");
+        throw new Error("client.kv.query is not implemented yet (deferred in the SDK overhaul).");
     }
     /**
      * Subscribe to realtime changes to this user's data across devices. Opens
@@ -5189,24 +5201,30 @@ class StorageNamespace {
      */
     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.");
+            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.");
         }
         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);
-        });
+            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 () => {
-            try {
-                socket.close();
-            }
-            catch { /* already closed */ }
+            transport.off(EventCoreEvents.MESSAGE, onMessage);
+            transport.disconnect();
         };
     }
     // -------------------------------------------------------------------------
@@ -5241,7 +5259,7 @@ class StorageNamespace {
     commitment() {
         const c = this.deps.session.commitment;
         if (!c)
-            throw new Error("client.storage: not signed in — call client.auth.zk.login() first.");
+            throw new Error("client.kv: not signed in — call client.auth.zk.login() first.");
         return c;
     }
     spacePath(suffix) {
@@ -5262,6 +5280,146 @@ class StorageNamespace {
     }
 }
 
+/**
+ * `client.storage` — file storage. Hides the `FileStorage` / `ShardClient` /
+ * `SharedSpaceClient` primitives behind the unified client.
+ *
+ *   const { stat, manifest } = await client.storage.writeFile({ spaceId, data, metadata })
+ *   const { data }          = await client.storage.readFile(spaceId, fileId)
+ *   const files             = await client.storage.listFiles()          // my shared files
+ *   const files             = await client.storage.listFiles({ spaceId }) // a space's files
+ *   await client.storage.deleteFile(spaceId, fileId)
+ *
+ * Model:
+ *   - **Files are written to a SharedSpace** (never the personal space). A file
+ *     is its manifest (per-chunk keys + global shard hashes); the manifest lives
+ *     in the space's gated, metered `/files` store, the shard ciphertext in the
+ *     global open `/api/shards` store.
+ *   - **The manifest is the capability** — anyone holding it reads the file from
+ *     the global shards, anywhere ({@link readByManifest}). Share a file by
+ *     sharing its manifest.
+ *   - **Personal discovery mirror** — on a successful write the SDK also records
+ *     the manifest in the user's `client.kv` under a reserved collection, so
+ *     {@link listFiles} (no `spaceId`) can show "files I've shared" without
+ *     enumerating spaces. The mirror is unmetered and is NOT a write path.
+ *
+ * For small structured values use `client.kv` instead.
+ */
+/** Reserved `client.kv` collection holding the personal manifest mirror. */
+const MIRROR_COLLECTION = "__files__";
+class StorageNamespace {
+    deps;
+    fileStorage = null;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * Write a file to a SharedSpace: shard ciphertext → the global store, the
+     * manifest → the space's gated store, and a mirror copy → the caller's
+     * personal index. Returns the `stat` and the `manifest` (share the manifest
+     * to let others read the file).
+     */
+    async writeFile(input) {
+        if (!input?.spaceId) {
+            throw new Error("client.storage.writeFile: `spaceId` is required (files live in a SharedSpace).");
+        }
+        const fs = this.fs();
+        const { manifest, stat } = await fs.writeFileToShards({
+            data: input.data,
+            metadata: input.metadata,
+        });
+        // Authoritative, metered write: the manifest into the space's gated store.
+        await this.space().writeFileManifest(input.spaceId, manifest);
+        // Best-effort personal discovery mirror (unmetered). A failure here
+        // leaves the file intact in the space — log and continue.
+        try {
+            await this.deps.kv.set(MIRROR_COLLECTION, manifest.id, {
+                spaceId: input.spaceId,
+                manifest,
+            });
+        }
+        catch (err) {
+            console.warn("client.storage.writeFile: discovery mirror failed (file still written):", err);
+        }
+        return { stat, manifest };
+    }
+    /** Read a file from its space (resolves the manifest, then the shards). */
+    async readFile(spaceId, fileId) {
+        return this.fs().readFile(spaceId, fileId);
+    }
+    /**
+     * Read a file straight from a manifest — the capability path. No space
+     * membership needed; this is how a shared file is opened.
+     */
+    async readByManifest(manifest) {
+        return this.fs().readFileFromShards(manifest);
+    }
+    /**
+     * List files. With no argument, returns the caller's own shared files from
+     * the personal mirror; with `{ spaceId }`, lists that space's files.
+     */
+    async listFiles(opts) {
+        if (opts?.spaceId)
+            return this.space().listFiles(opts.spaceId);
+        const ids = await this.deps.kv.list(MIRROR_COLLECTION);
+        const entries = await Promise.all(ids.map((id) => this.deps.kv.get(MIRROR_COLLECTION, id)));
+        return entries
+            .filter((e) => Boolean(e?.manifest))
+            .map((e) => manifestToStat(e.manifest));
+    }
+    /** Delete a file from its space and remove the personal mirror entry. */
+    async deleteFile(spaceId, fileId) {
+        const existed = await this.fs().deleteFile(spaceId, fileId);
+        try {
+            await this.deps.kv.delete(MIRROR_COLLECTION, fileId);
+        }
+        catch {
+            // mirror cleanup is best-effort
+        }
+        return existed;
+    }
+    /** Read a manifest verbatim (e.g. to share a file). */
+    async getManifest(spaceId, fileId) {
+        return this.fs().readManifest(spaceId, fileId);
+    }
+    // -------------------------------------------------------------------------
+    // Internals — lazily built so an unauthenticated client is cheap to create.
+    // -------------------------------------------------------------------------
+    fs() {
+        if (!this.fileStorage) {
+            this.fileStorage = new FileStorage({
+                shards: this.shards(),
+                space: this.space(),
+                rsWasmModule: this.deps.rsWasmModule,
+            });
+        }
+        return this.fileStorage;
+    }
+    _shards = null;
+    shards() {
+        // Global, content-addressed shard store. The credential-stamping fetch
+        // attaches the app key so PUTs are attributed + quota-gated; GETs are open.
+        if (!this._shards) {
+            this._shards = new ShardClient({
+                baseUrl: this.deps.baseUrl,
+                pathPrefix: "/api/shards",
+                fetch: this.deps.http.fetch,
+            });
+        }
+        return this._shards;
+    }
+    _space = null;
+    space() {
+        if (!this._space) {
+            this._space = new SharedSpaceClient({
+                baseUrl: this.deps.baseUrl,
+                fetch: this.deps.http.fetch,
+            });
+        }
+        return this._space;
+    }
+}
+
 /**
  * SpaceCipher — pure crypto for the fan-out group-encryption layer.
  *
@@ -5570,23 +5728,7 @@ class Space {
      * persisted `spaceMessage`. Requires a keyring.
      */
     async sendMessage(payload, opts = {}) {
-        const cipher = this.requireCipher(opts.contentType);
-        const message = new Message(payload);
-        const headers = await cipher.seal(message.serialize());
-        const source = this.deps.myId();
-        const subject = opts.channel ?? "default";
-        // Sign the message with our identity ECDSA key so receivers can verify
-        // authorship end-to-end (independent of the relay's `source` stamp).
-        const authPriv = KeyStore.getInstance().getAuthKeyPair(source)?.privateKey;
-        if (authPriv) {
-            const canonical = canonicalMessage({
-                source, target: this.name, subject,
-                epoch: Number(headers.epoch), iv: String(headers.iv), ciphertext: String(headers.ciphertext),
-            });
-            headers.sig = await signSpaceMessage(canonical, authPriv);
-        }
-        const packet = new Packet({ subject, source, target: this.name, headers });
-        this.sendRaw({ spaceMessage: packet.serialize() });
+        this.sendRaw({ spaceMessage: await this.sealMessage(payload, opts.channel, opts.contentType) });
     }
     /** Subscribe to decrypted fan-out messages. Returns an unsubscribe fn. */
     onMessage(handler) {
@@ -5594,6 +5736,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);
@@ -5683,9 +5875,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 });
@@ -5705,11 +5901,39 @@ class Space {
         if (!f || typeof f !== "object")
             return;
         if (typeof f.spaceMessage === "string" && this.cipher) {
-            const decoded = await this.decodeFrame(f.spaceMessage, this.cipher, /*raw*/ true);
+            const decoded = await this.decodeFrame(f.spaceMessage, this.cipher, /*raw*/ true, Number(f.timestamp ?? 0));
             if (decoded)
                 this.emitEvent("message", decoded);
             return;
         }
+        if (f.editSpaceMessage && typeof f.editSpaceMessage === "object" && this.cipher) {
+            // Server-authoritative in-place edit: new sealed content at the same
+            // handle. Decode and surface it; the app replaces by `handle`.
+            const e = f.editSpaceMessage;
+            if (typeof e.spaceMessage === "string") {
+                const decoded = await this.decodeFrame(e.spaceMessage, this.cipher, /*raw*/ true, Number(e.ts ?? 0));
+                if (decoded)
+                    this.emitEvent("message-edited", decoded);
+            }
+            return;
+        }
+        if (f.deleteSpaceMessage && typeof f.deleteSpaceMessage === "object") {
+            const d = f.deleteSpaceMessage;
+            this.emitEvent("message-deleted", { handle: Number(d.ts ?? 0) });
+            return;
+        }
+        if (f.pub && typeof f.pub === "object") {
+            // Generic ephemeral relay frame. The server stamps the authenticated
+            // sender as `name`; `pub` carries the app's {subject, data}. We
+            // surface the authenticated `name` as `from` (not any client-set
+            // value inside `pub`), so app signals can't spoof their sender.
+            const p = f.pub;
+            const from = typeof f.name === "string" ? f.name : "";
+            if (from && typeof p.subject === "string") {
+                this.emitEvent("ephemeral", { from, subject: p.subject, data: p.data });
+            }
+            return;
+        }
         if (f.joinRequest && typeof f.joinRequest === "object") {
             const req = f.joinRequest;
             this.emitEvent("join-request", req);
@@ -5726,19 +5950,46 @@ class Space {
             void this.deps.keyring.pullKeys().catch(() => { });
         }
     }
+    /**
+     * Seal `payload` once with the current group key + sign it, returning the
+     * serialized `Packet` string. Shared by send (a new message) and edit
+     * (replacement content for an existing handle). Requires a keyring.
+     */
+    async sealMessage(payload, channel, contentType) {
+        const cipher = this.requireCipher(contentType);
+        const message = new Message(payload);
+        const headers = await cipher.seal(message.serialize());
+        const source = this.deps.myId();
+        const subject = channel ?? "default";
+        // Sign with our identity ECDSA key so receivers can verify authorship
+        // end-to-end (independent of the relay's `source` stamp).
+        const authPriv = KeyStore.getInstance().getAuthKeyPair(source)?.privateKey;
+        if (authPriv) {
+            const canonical = canonicalMessage({
+                source, target: this.name, subject,
+                epoch: Number(headers.epoch), iv: String(headers.iv), ciphertext: String(headers.ciphertext),
+            });
+            headers.sig = await signSpaceMessage(canonical, authPriv);
+        }
+        return new Packet({ subject, source, target: this.name, headers }).serialize();
+    }
     /**
      * Decode one persisted/broadcast frame into a SpaceMessageEvent.
      * `isRawFrame` true means `input` is the already-extracted `spaceMessage`
-     * packet string; false means it's the full `{spaceMessage, name, ...}` frame.
+     * packet string (and `serverTs` carries the message's storage handle from
+     * the enclosing frame); false means `input` is the full
+     * `{spaceMessage, name, timestamp}` frame and the handle is read from it.
      */
-    async decodeFrame(input, cipher, isRawFrame = false) {
+    async decodeFrame(input, cipher, isRawFrame = false, serverTs = 0) {
         try {
             let packetJson = input;
+            let handle = serverTs;
             if (!isRawFrame) {
                 const outer = JSON.parse(input);
                 if (typeof outer.spaceMessage !== "string")
                     return null;
                 packetJson = outer.spaceMessage;
+                handle = Number(outer.timestamp ?? 0);
             }
             const packet = Packet.deserialize(packetJson);
             if (!cipher.handles(packet.headers))
@@ -5759,6 +6010,7 @@ class Space {
                 channel: packet.subject,
                 epoch: Number(packet.headers?.epoch ?? 0),
                 contentType: packet.headers?.contentType,
+                handle,
                 message,
             };
         }
@@ -6509,7 +6761,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;
@@ -6517,6 +6771,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);
@@ -6528,19 +6786,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,
@@ -6557,6 +6820,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;
+    }
 }
 
 /**
@@ -6625,5 +6930,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, MemorySessionStore, Message, Message as MessageDefault, MessageNamespace, PBKDF2_DEFAULT_ITERATIONS, PREIMAGE_POK_VERIFICATION_KEY, Packet, PersonalSpaceClient, Poseidon, PreimagePoK, ReedSolomonCodec, Space as Room, SerializeMessage, SessionState, ShardClient, SharedSpaceClient, Space, SpaceKeyring, SpaceNamespace, SpacePacketCipher, StorageNamespace, WSTransport, ZkAuth, buildCommitment, compilePrograms, decodeFromHex, decorators, decryptAesGcm, defaultCircuitUrls, defaultSessionStore, deriveAesKeyFromPassphrase, deriveBitsHkdf, deriveIdentity, encodeToHex, encryptAesGcm, exportPublicKeyBase64, exportPublicKeyHex, generateAuthProof, getSubtle, initBn128Wasm, initRsWasm, initializeCircuits, manifestToStat, poseidonHash, quickVerify, randomBytes, shardHash, signMessage, toField, unwrapWithPassphrase, verify, 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, MemorySessionStore, Message, Message as MessageDefault, MessageNamespace, PBKDF2_DEFAULT_ITERATIONS, PREIMAGE_POK_VERIFICATION_KEY, Packet, PersonalSpaceClient, Poseidon, PreimagePoK, ReedSolomonCodec, Space as Room, SerializeMessage, SessionState, ShardClient, SharedSpaceClient, Space, SpaceKeyring, SpaceNamespace, SpacePacketCipher, StorageNamespace, WSTransport, ZkAuth, buildCommitment, compilePrograms, decodeFromHex, decorators, decryptAesGcm, defaultCircuitUrls, defaultSessionStore, deriveAesKeyFromPassphrase, deriveBitsHkdf, deriveIdentity, encodeToHex, encryptAesGcm, exportPublicKeyBase64, exportPublicKeyHex, generateAuthProof, getSubtle, initBn128Wasm, initRsWasm, initializeCircuits, manifestToStat, poseidonHash, quickVerify, randomBytes, shardHash, signMessage, toField, unwrapWithPassphrase, verify, verifyGroth16, verifyHashKnowledge, verifyPreimagePoK, wrapWithPassphrase };
 //# sourceMappingURL=index.js.map