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

package/dist/browser/index.js

@@ -2383,11 +2383,31 @@ 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;
+    urlProvider;
     socket = null;
     _isConnected = false;
     _isConnecting = false;
@@ -2400,16 +2420,29 @@ class WSTransport extends EventCore {
     // Outbound queue (raw frame strings — already serialized by caller)
     outboundQueue = [];
     maxQueueSize;
+    // Heartbeat / liveness state
+    heartbeatInterval;
+    heartbeatTimeout;
+    pingFrame;
+    pongFrame;
+    heartbeatTimer = null;
+    pongTimer = null;
     constructor(opts) {
         super();
         if (!opts || !opts.url) {
             throw new Error("WSTransport: `url` is required");
         }
         this.url = opts.url;
+        this.urlProvider = opts.urlProvider;
+        this.id = opts.id ?? `ws${++__wsInstanceSeq}`;
         this.autoReconnect = opts.autoReconnect ?? true;
         this.reconnectDelay = opts.reconnectDelay ?? 3000;
         this.maxReconnectAttempts = opts.maxReconnectAttempts ?? 5;
         this.maxQueueSize = opts.maxQueueSize ?? 100;
+        this.heartbeatInterval = opts.heartbeatInterval ?? 30000;
+        this.heartbeatTimeout = opts.heartbeatTimeout ?? 10000;
+        this.pingFrame = opts.pingFrame ?? "ping";
+        this.pongFrame = opts.pongFrame ?? "pong";
     }
     /** Open the socket. Resolves when CONNECTED fires. Rejects on first error. */
     async connect() {
@@ -2417,6 +2450,18 @@ class WSTransport extends EventCore {
             throw new Error("WSTransport: already connected or connecting");
         }
         this._isConnecting = true;
+        // On a RECONNECT, refresh the URL (the baked-in single-use ticket is spent).
+        // The first connect uses `url` as-is. If the provider throws (e.g. can't
+        // mint a ticket), surface it and let scheduleReconnect retry.
+        if (this.urlProvider && this.reconnectAttempts > 0) {
+            try {
+                this.url = await this.urlProvider();
+            }
+            catch (err) {
+                this._isConnecting = false;
+                throw err;
+            }
+        }
         return new Promise((resolve, reject) => {
             try {
                 const socket = new WebSocket(this.url);
@@ -2427,9 +2472,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 +2499,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 +2518,7 @@ class WSTransport extends EventCore {
             clearTimeout(this.reconnectTimeout);
             this.reconnectTimeout = null;
         }
+        this.stopHeartbeat();
         this.autoReconnect = false;
         if (this.socket) {
             try {
@@ -2492,6 +2549,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) {
@@ -2505,7 +2634,12 @@ class WSTransport extends EventCore {
                 await this.connect();
             }
             catch {
-                // scheduleReconnect will fire again from onclose
+                // A failed reconnect never opened the socket, so its `onclose` won't
+                // re-schedule (that path is guarded by `wasConnected`). Re-schedule here
+                // so we keep retrying (with a fresh ticket each time) until we succeed
+                // or hit the attempt cap.
+                if (this.autoReconnect)
+                    this.scheduleReconnect();
             }
         }, this.reconnectDelay);
     }
@@ -3040,7 +3174,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 +3188,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 +3297,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 +3308,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,
@@ -3821,6 +3955,8 @@ class FileStorage {
         const fileId = input.fileId ?? generateId();
         const createdAt = Date.now();
         const chunks = [];
+        const totalChunks = Math.max(1, Math.ceil(data.length / this.chunkSize));
+        input.onProgress?.(0, totalChunks);
         // Slicing + encrypting + encoding + uploading is done per-chunk so
         // the peak memory footprint stays at ~chunkSize even for huge files.
         // Within a chunk, the shard uploads are parallelized up to
@@ -3830,6 +3966,7 @@ class FileStorage {
             const end = Math.min(start + this.chunkSize, data.length);
             const plaintext = data.subarray(start, end);
             chunks.push(await this.writeChunk(plaintext, chunkIndex));
+            input.onProgress?.(chunks.length, totalChunks);
             // Stop after one iteration if the file is empty — we still emit a
             // single zero-length chunk so the manifest has a stable shape.
             if (data.length === 0)
@@ -4017,248 +4154,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 +4675,7 @@ class HttpClient {
     baseUrl;
     apiKey;
     getSessionToken;
+    onUnauthorized;
     fetchFn;
     constructor(opts) {
         if (!opts?.baseUrl)
@@ -4699,6 +4683,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`.");
@@ -4728,10 +4713,13 @@ class HttpClient {
     post(path, body) {
         return this.request("POST", path, body);
     }
+    patch(path, body) {
+        return this.request("PATCH", path, body);
+    }
     del(path, body) {
         return this.request("DELETE", path, body);
     }
-    async request(method, path, body) {
+    async request(method, path, body, allowRecovery = true) {
         const url = path.startsWith("http") ? path : `${this.baseUrl}${path.startsWith("/") ? "" : "/"}${path}`;
         const init = { method };
         if (body !== undefined) {
@@ -4739,6 +4727,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 +4965,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 +5160,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 +5175,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 +5215,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 +5226,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 +5284,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 +5305,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.
  *
@@ -5501,12 +5684,27 @@ class Space {
     /** Open the space websocket (resolves the ticket + identity lazily). */
     async connect() {
         if (!this.channel) {
-            const ticket = await this.deps.fetchTicket();
-            const url = `${this.deps.wsBaseUrl}/api/spaces/${encodeURIComponent(this.name)}/websocket` +
-                (ticket ? `?ticket=${encodeURIComponent(ticket)}` : "");
+            // The WS upgrade ticket is single-use + short-TTL, so a reconnect
+            // must mint a FRESH one — otherwise the socket drops (idle timeout,
+            // network blip) and never comes back. `buildUrl` is handed to the
+            // transport as a `urlProvider` it calls before each reconnect.
+            const buildUrl = async () => {
+                const ticket = await this.deps.fetchTicket();
+                return (`${this.deps.wsBaseUrl}/api/spaces/${encodeURIComponent(this.name)}/websocket` +
+                    (ticket ? `?ticket=${encodeURIComponent(ticket)}` : ""));
+            };
+            const url = await buildUrl();
             this.channel = this.deps.createChannel
                 ? this.deps.createChannel(url, this.deps.myId())
-                : new BroadcastChannel({ url, myId: this.deps.myId(), autoAnnounce: false });
+                : new BroadcastChannel({
+                    url,
+                    myId: this.deps.myId(),
+                    autoAnnounce: false,
+                    urlProvider: buildUrl,
+                    // Keep recovering across network flaps (each attempt mints a
+                    // fresh ticket); teardown calls disconnect() which stops it.
+                    maxReconnectAttempts: 0,
+                });
             for (const [event, handler] of this.pending)
                 this.channel.on(event, handler);
             this.pending.length = 0;
@@ -5570,23 +5768,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 +5776,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);
@@ -5676,16 +5908,20 @@ class Space {
         return this.requireKeyring().rotate(roster);
     }
     // -- room-scoped files (no websocket needed) -------------------------------
-    async putFile(file, metadata) {
-        return this.fileStorage().writeFileToShards({ data: file, metadata });
+    async putFile(file, metadata, opts = {}) {
+        return this.fileStorage().writeFileToShards({ data: file, metadata, onProgress: opts.onProgress });
     }
     async getFile(manifest) {
         return this.fileStorage().readFileFromShards(manifest);
     }
     fileStorage() {
+        // Global, content-addressed shard store — same store `client.storage`
+        // uses, so a file shared into a channel resolves from anywhere by
+        // manifest. (Shards are encrypted ciphertext; the manifest is the
+        // capability.)
         const shards = new ShardClient({
             baseUrl: this.deps.httpBaseUrl,
-            pathPrefix: `/api/spaces/${encodeURIComponent(this.name)}/shards`,
+            pathPrefix: "/api/shards",
             fetch: this.deps.fetch,
         });
         return new FileStorage({ shards });
@@ -5705,11 +5941,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 +5990,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 +6050,7 @@ class Space {
                 channel: packet.subject,
                 epoch: Number(packet.headers?.epoch ?? 0),
                 contentType: packet.headers?.contentType,
+                handle,
                 message,
             };
         }
@@ -5774,6 +6066,12 @@ class Space {
      * nothing to verify against → reject.
      */
     async verifySender(packet) {
+        // Trust our OWN messages — we sent them, so there's nothing to prove
+        // against the roster. This also keeps a returning member (who loaded a
+        // cached key and never re-published a join-request) from dropping the
+        // echo of their own messages when their `ecdsaPub` isn't in the roster.
+        if (packet.source === this.deps.myId())
+            return true;
         const keyring = this.deps.keyring;
         const sig = packet.headers?.sig;
         if (!keyring || typeof sig !== "string")
@@ -6270,6 +6568,34 @@ class KeyringClient {
     async invite(username) {
         await this.post("/keyring/invite", { username });
     }
+    // -- Shareable invite links ----------------------------------------------
+    // A capability token tied to this space. Redeeming it allowlists the holder
+    // so the keeper admits them — the link IS the invitation. Mint/list/revoke
+    // require the caller to be the creator or an existing member.
+    async createInviteLink(opts = {}) {
+        return this.post("/keyring/link", opts);
+    }
+    async listInviteLinks() {
+        const body = await this.get("/keyring/links");
+        return body.links ?? [];
+    }
+    /** Set a member's role ("viewer" | "editor"). Owner-only on the server. */
+    async setMemberRole(username, role) {
+        await this.post("/keyring/role", { username, role });
+    }
+    /** Roster with roles (owner/members only). */
+    async members() {
+        const body = await this.get("/keyring/members");
+        return body.members ?? [];
+    }
+    async revokeInviteLink(token) {
+        await this.post("/keyring/link-revoke", { token });
+    }
+    /** Redeem a link: the server allowlists this member and asks the keeper to
+     *  wrap the group key for their identity. Caller must be authenticated. */
+    async redeemInvite(req) {
+        await this.post("/keyring/redeem", req);
+    }
     async fetchMetadata() {
         try {
             return await this.get("/metadata");
@@ -6407,6 +6733,56 @@ class SpaceNamespace {
         return this.joinSpace(spaceId, opts);
     }
     // -------------------------------------------------------------------------
+    // Invite links — shareable, keeper-gated invitations to a space. The token
+    // is a capability: anyone signed in who redeems it is admitted by the
+    // keeper. Mint/list/revoke require the caller to be the space's creator or
+    // an existing member.
+    // -------------------------------------------------------------------------
+    /** Mint a shareable invite link for a space. `opts.expiresInSec` / `maxUses`
+     *  bound it (0/undefined = unlimited); `opts.role` ("viewer"|"editor") is the
+     *  access granted to redeemers (default viewer). Returns the link. */
+    async createInviteLink(spaceId, opts = {}) {
+        return this.keyringFor(spaceId).createInviteLink(opts);
+    }
+    /** Set a member's role on a space ("viewer" | "editor"). Owner-only. */
+    async setMemberRole(spaceId, username, role) {
+        await this.keyringFor(spaceId).setMemberRole(username, role);
+    }
+    /** Roster with roles (owner/members only). */
+    async members(spaceId) {
+        return this.keyringFor(spaceId).members();
+    }
+    /** List a space's active invite links (creator/members only). */
+    async listInviteLinks(spaceId) {
+        return this.keyringFor(spaceId).listInviteLinks();
+    }
+    /** Revoke an invite link by token. */
+    async revokeInviteLink(spaceId, token) {
+        await this.keyringFor(spaceId).revokeInviteLink(token);
+    }
+    /**
+     * Join a space using an invite link: redeem the token (the keeper admits
+     * this member), then connect and resolve once the group key arrives.
+     * Returns the open {@link Space}.
+     */
+    async joinByInvite(spaceId, token, opts = {}) {
+        const memberId = this.myId();
+        const { ecdhPub, ecdsaPub } = await this.ensureIdentity(memberId);
+        await this.keyringFor(spaceId).redeemInvite({ token, identityEcdhPub: ecdhPub, identityEcdsaPub: ecdsaPub });
+        return this.joinSpace(spaceId, opts);
+    }
+    /** The current member roster of a space (member id → identity public keys). */
+    async roster(spaceId) {
+        return this.keyringFor(spaceId).fetchRoster();
+    }
+    keyringFor(spaceId) {
+        return new KeyringClient({
+            spaceId,
+            httpBaseUrl: this.deps.http.baseUrl,
+            fetch: this.deps.http.fetch,
+        });
+    }
+    // -------------------------------------------------------------------------
     // Internals
     // -------------------------------------------------------------------------
     async build(spaceId, historyPolicy) {
@@ -6473,6 +6849,133 @@ class SpaceNamespace {
     }
 }
 
+/**
+ * `client.agents` — manage an app's **Programmable Agents** (server-side
+ * "virtual users" backed by Workers AI).
+ *
+ *   const { config } = await client.agents.create(appId, {
+ *     handle: '@assistant', displayName: 'Assistant',
+ *     systemPrompt: 'You are a helpful teammate in this Space.',
+ *     triggers: [{ type: 'mention' }],
+ *   });
+ *   await client.agents.enable(appId, config.agentId, spaceId);  // per-Space opt-in
+ *
+ * These are MANAGEMENT calls — the agent itself runs on the accelerator. Only an
+ * app's owner or an editor of its shared Space may create/update/enable an agent
+ * (viewers can read). Authorization rides the user session token; non-owner
+ * editors pass their management Space via `opts.space`.
+ *
+ * v1 is "prompts + persona": a system prompt, a model, named prompt `skills`,
+ * and `triggers` that decide when the agent speaks. No tools, no code.
+ */
+class AgentsNamespace {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** List the app's agents. */
+    async list(appId, opts = {}) {
+        const res = await this.deps.http.get(this.path(appId, "", opts));
+        return res.agents ?? [];
+    }
+    /** Read one agent (config + identity keys). */
+    async get(appId, agentId, opts = {}) {
+        return this.deps.http.get(this.path(appId, `/${encodeURIComponent(agentId)}`, opts));
+    }
+    /** Create an agent (owner/editor only). */
+    async create(appId, input, opts = {}) {
+        return this.deps.http.post(this.path(appId, "", {}), { ...input, space: opts.space });
+    }
+    /** Update an agent's editor-settable fields (owner/editor only). */
+    async update(appId, agentId, patch, opts = {}) {
+        return this.deps.http.patch(this.path(appId, `/${encodeURIComponent(agentId)}`, {}), { ...patch, space: opts.space });
+    }
+    /** Delete an agent (owner/editor only). */
+    async delete(appId, agentId, opts = {}) {
+        return this.deps.http.del(this.path(appId, `/${encodeURIComponent(agentId)}`, {}), { space: opts.space });
+    }
+    /** Enable the agent on a Space (per-Space opt-in). */
+    async enable(appId, agentId, spaceId, opts = {}) {
+        return this.deps.http.post(this.path(appId, `/${encodeURIComponent(agentId)}/enable`, {}), { targetSpaceId: spaceId, space: opts.space });
+    }
+    /** Disable the agent on a Space. */
+    async disable(appId, agentId, spaceId, opts = {}) {
+        return this.deps.http.post(this.path(appId, `/${encodeURIComponent(agentId)}/disable`, {}), { targetSpaceId: spaceId, space: opts.space });
+    }
+    path(appId, suffix, opts) {
+        const q = opts.space ? `?space=${encodeURIComponent(opts.space)}` : "";
+        return `/api/apps/${encodeURIComponent(appId)}/agents${suffix}${q}`;
+    }
+}
+
+/**
+ * `client.functions` — manage an app's **serverless functions** (developer-
+ * authored code that runs on the accelerator).
+ *
+ *   const { config } = await client.functions.deploy(appId, {
+ *     name: 'hello', displayName: 'Hello',
+ *     code: `export default { fetch: () => new Response('hi') }`,
+ *     triggers: { http: { enabled: true } },
+ *   });
+ *   // HTTP-reachable at  hello--<slug>.fns.muhkoo.dev
+ *   await client.functions.enable(appId, config.functionId, spaceId); // Space-bound
+ *
+ * These are MANAGEMENT calls — the function itself runs on the accelerator
+ * (uploaded just-in-time, decrypted only at invocation). Only an app's owner or
+ * an editor of its shared Space may deploy/update/enable (viewers read).
+ * Authorization rides the user session token; non-owner editors pass their
+ * management Space via `opts.space`.
+ *
+ * v1 is "compute-only": a function is an untrusted single-module ES worker
+ * (`export default { fetch }`) with NO platform bindings — it reaches the
+ * platform as an external client (the end-user session is passed through). Two
+ * triggers: `http` (its own subdomain) and `space` (invoked on Space messages,
+ * like a Programmable Agent).
+ */
+class FunctionsNamespace {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** List the app's functions. */
+    async list(appId, opts = {}) {
+        const res = await this.deps.http.get(this.path(appId, "", opts));
+        return res.functions ?? [];
+    }
+    /** Read one function's config. */
+    async get(appId, functionId, opts = {}) {
+        return this.deps.http.get(this.path(appId, `/${encodeURIComponent(functionId)}`, opts));
+    }
+    /** Read a function's decrypted source (owner/editor; for the editor UI). */
+    async code(appId, functionId, opts = {}) {
+        return this.deps.http.get(this.path(appId, `/${encodeURIComponent(functionId)}/code`, opts));
+    }
+    /** Deploy (create) a function (owner/editor only). */
+    async deploy(appId, input, opts = {}) {
+        return this.deps.http.post(this.path(appId, "", {}), { ...input, space: opts.space });
+    }
+    /** Update a function's editor-settable fields and/or redeploy its `code`. */
+    async update(appId, functionId, patch, opts = {}) {
+        return this.deps.http.patch(this.path(appId, `/${encodeURIComponent(functionId)}`, {}), { ...patch, space: opts.space });
+    }
+    /** Delete a function (owner/editor only). */
+    async delete(appId, functionId, opts = {}) {
+        return this.deps.http.del(this.path(appId, `/${encodeURIComponent(functionId)}`, {}), { space: opts.space });
+    }
+    /** Enable the function on a Space (per-Space opt-in for the `space` trigger). */
+    async enable(appId, functionId, spaceId, opts = {}) {
+        return this.deps.http.post(this.path(appId, `/${encodeURIComponent(functionId)}/enable`, {}), { targetSpaceId: spaceId, space: opts.space });
+    }
+    /** Disable the function on a Space. */
+    async disable(appId, functionId, spaceId, opts = {}) {
+        return this.deps.http.post(this.path(appId, `/${encodeURIComponent(functionId)}/disable`, {}), { targetSpaceId: spaceId, space: opts.space });
+    }
+    path(appId, suffix, opts) {
+        const q = opts.space ? `?space=${encodeURIComponent(opts.space)}` : "";
+        return `/api/apps/${encodeURIComponent(appId)}/functions${suffix}${q}`;
+    }
+}
+
 /**
  * `Client` — the single entry point to the Muhkoo SDK.
  *
@@ -6509,14 +7012,24 @@ class Client {
     baseUrl;
     /** Authentication — `client.auth.zk.login(...)`, etc. */
     auth;
-    /** Per-user persistent storage — `client.storage.set(...)`, etc. */
+    /** Per-user key/value storage — `client.kv.set(...)`, etc. */
+    kv;
+    /** File storage — `client.storage.writeFile(...)`, etc. */
     storage;
     /** Realtime messaging — `client.message.subscribe(...)`, etc. */
     message;
     /** Fan-out group spaces — `client.space.createSpace(...)`, etc. */
     space;
+    /** Programmable Agents — `client.agents.create(appId, …)`, etc. */
+    agents;
+    /** Serverless functions — `client.functions.deploy(appId, …)`, etc. */
+    functions;
     session;
     http;
+    /** Subscribers notified when a session expires and can't be recovered. */
+    sessionExpiredHandlers = new Set();
+    /** Shared in-flight recovery so a burst of 401s triggers one re-auth. */
+    recoverInFlight = null;
     constructor(options = {}) {
         if (options.logLevel && typeof globalThis.appLogger?.setLevel === "function") {
             globalThis.appLogger.setLevel(options.logLevel);
@@ -6528,19 +7041,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,
@@ -6548,6 +7066,8 @@ class Client {
             wsBaseUrl,
             cache: spaceKeyCache,
         });
+        this.agents = new AgentsNamespace({ http: this.http });
+        this.functions = new FunctionsNamespace({ http: this.http });
     }
     /** The currently signed-in user, or `null`. */
     get user() {
@@ -6557,6 +7077,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 +7187,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, AgentsNamespace, AuthClient, AuthNamespace, AuthPublicInput, Authenticator, BroadcastChannel, BroadcastChannelEvents, ChannelExistsError, ChannelNotFoundError, ChunkCipher, Client, DEFAULT_BASE_URL, DoubleRatchet, DoubleRatchetCipher, DoubleRatchetManager, EncryptedSession, EventCore, EventCoreEvents, Field, Field as FieldElement, FileStorage, FunctionsNamespace, HashKnowledge, HttpClient, HttpError, KEEPER_MEMBER_ID, KeyStore, KeyringClient, KvNamespace, LocalStorageSessionStore, 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