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

package/dist/connect.d.ts

@@ -936,6 +936,14 @@ declare class EncryptedSession {
 interface WSTransportOptions {
     /** WebSocket URL, e.g. `ws://localhost:8787/foo`. */
     url: string;
+    /**
+     * Stable identifier for this connection (a channel / space / personal-space
+     * id). Lifecycle + MESSAGE events are namespaced by it on the shared
+     * `EventCore` bus so concurrent transports (chat room A, room B, the storage
+     * feed, …) never receive each other's frames. Optional — a unique id is
+     * generated when omitted; pass a semantic one for clearer debugging.
+     */
+    id?: string;
     /** Reconnect automatically after unexpected disconnect (default `true`). */
     autoReconnect?: boolean;
     /** Delay between reconnect attempts in ms (default `3000`). */
@@ -947,11 +955,41 @@ interface WSTransportOptions {
      * throws synchronously. Default `100`.
      */
     maxQueueSize?: number;
+    /**
+     * Heartbeat interval in ms. While connected, a `pingFrame` is sent every
+     * interval to keep the socket warm (long-lived WebSockets get dropped by CF
+     * / intermediaries when idle) and to detect a silently-dead connection.
+     * Default `30000`. Set `0` to disable the heartbeat entirely.
+     */
+    heartbeatInterval?: number;
+    /**
+     * How long (ms) to wait for a `pongFrame` after sending a ping before
+     * treating the connection as dead and forcing a reconnect. Should be well
+     * under `heartbeatInterval`. Default `10000`.
+     */
+    heartbeatTimeout?: number;
+    /** Outbound keep-alive frame. Default `"ping"`. */
+    pingFrame?: string;
+    /**
+     * Inbound keep-alive ack. Matching frames are swallowed (never surfaced as a
+     * `MESSAGE`) and reset the liveness timer. Must match the server's
+     * auto-response. Default `"pong"`.
+     */
+    pongFrame?: string;
 }
 declare class WSTransport extends EventCore {
-    emit: typeof EventCore.emit;
-    on: typeof EventCore.on;
-    off: typeof 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.
+     */
+    readonly id: string;
+    readonly emit: (event: EventCoreEvents, data: unknown) => void;
+    readonly on: (event: EventCoreEvents, handler: EventListener | CallableFunction) => void;
+    readonly off: (event: EventCoreEvents, handler: EventListener | CallableFunction) => void;
+    private scopedEvent;
     private url;
     private socket;
     private _isConnected;
@@ -963,6 +1001,12 @@ declare class WSTransport extends EventCore {
     private reconnectTimeout;
     private outboundQueue;
     private maxQueueSize;
+    private heartbeatInterval;
+    private heartbeatTimeout;
+    private pingFrame;
+    private pongFrame;
+    private heartbeatTimer;
+    private pongTimer;
     constructor(opts: WSTransportOptions);
     /** Open the socket. Resolves when CONNECTED fires. Rejects on first error. */
     connect(): Promise<void>;
@@ -977,6 +1021,25 @@ declare class WSTransport extends EventCore {
     isConnecting(): boolean;
     queuedFrames(): number;
     reconnectAttemptCount(): number;
+    /** Begin the keep-alive loop (no-op when disabled). */
+    private startHeartbeat;
+    /** Stop the keep-alive loop and clear any pending liveness deadline. */
+    private stopHeartbeat;
+    /**
+     * 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).
+     */
+    private sendHeartbeat;
+    /**
+     * 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.
+     */
+    private forceReconnect;
     private scheduleReconnect;
     private flushQueue;
 }
@@ -1382,123 +1445,50 @@ declare class ShardClient {
 }
 
 /**
- * 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`.
+ * HTTP client for the gated file-manifest store on a SharedSpace
+ * (`/api/spaces/:spaceId/files`).
  *
- * Wire protocol (this client implements the client side; the server side is
- * the next slice of work in accelerator):
+ * 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.
  *
- *   POST /api/spaces                                 create a new space (gated by caller proof)
- *     body: { challengeId, proof, publicSignals, initialAcl? }
- *     returns: { spaceId }
+ * 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.
  *
- *   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 }
+ * 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 }
  */
 
 interface SharedSpaceClientOptions {
-    /** Base URL of the accelerator. */
+    /** Base URL of the accelerator (e.g. `https://api.muhkoo.dev`). */
     baseUrl: string;
-    /** This caller's Poseidon commitment (decimal string). */
-    commitment: string;
-    /** Private witnesses for the `preimagePoK` circuit. */
-    secret: string;
-    salt: string;
-    ecdsaPub: string;
-    /** Public signal: Poseidon hash of `ecdsaPub`. */
-    ecdsaPubHash: string;
-    /** Compiled circuit assets — same files PersonalSpaceClient uses. */
-    circuits: {
-        wasmUrl: string;
-        zkeyUrl: string;
-    };
-    /** Optional custom fetch (defaults to `globalThis.fetch`). */
+    /**
+     * Credential-stamping fetch — pass {@link HttpClient.fetch} so requests
+     * carry the app key + session token. Defaults to `globalThis.fetch`
+     * (unauthenticated; only useful in tests).
+     */
     fetch?: typeof fetch;
 }
 declare class SharedSpaceClient {
     private readonly baseUrl;
-    private readonly commitment;
-    private readonly secret;
-    private readonly salt;
-    private readonly ecdsaPub;
-    private readonly ecdsaPubHash;
-    private readonly wasmUrl;
-    private readonly zkeyUrl;
     private readonly fetchFn;
     constructor(opts: SharedSpaceClientOptions);
-    /**
-     * 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).
-     */
-    createSpace(initialAcl?: ACLEntry[]): Promise<{
-        spaceId: string;
-    }>;
-    /** Write a file manifest into the space. Requires `write` permission. */
+    /** Write a file manifest into the space. Requires space membership. */
     writeFileManifest(spaceId: string, manifest: FileManifest): Promise<void>;
-    /** Read a file manifest by id. Requires `read` permission. */
+    /** Read a file manifest by id. Requires space membership. */
     readFileManifest(spaceId: string, fileId: string): Promise<FileManifest>;
-    /** Delete a file manifest by id. Requires `delete` permission. */
+    /** Delete a file manifest by id. Requires space membership. */
     deleteFileManifest(spaceId: string, fileId: string): Promise<boolean>;
-    /** List file summaries in the space. Requires `read` permission. */
+    /** List file summaries in the space. Requires space membership. */
     listFiles(spaceId: string): Promise<FileStat[]>;
-    /** Add a participant. Requires `invite` or `admin`. */
-    addParticipant(spaceId: string, participant: Participant): Promise<void>;
-    /** Remove a participant by their public-key identity. Requires `admin`. */
-    removeParticipant(spaceId: string, participantCommitment: string): Promise<boolean>;
-    /** Set / replace an ACL entry. Requires `admin`. */
-    setACLEntry(spaceId: string, entry: ACLEntry): Promise<void>;
-    /** Request a challenge for `spaceId` and generate the matching proof. */
-    private proveFreshChallenge;
-    /**
-     * Hit `/challenge`. The body includes the caller's commitment so the
-     * server can scope the issued nonce to this principal.
-     */
-    private requestChallenge;
+    private filesBase;
     private jsonRequest;
 }
 
@@ -2158,6 +2148,30 @@ declare class ZkAuth {
      * both the session and the identity are stored on the client.
      */
     login(username: string, password: string, opts?: LoginOptions): Promise<AuthUser>;
+    /**
+     * 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.
+     */
+    recover(): Promise<boolean>;
+    /**
+     * 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).
+     */
+    private proveAndStore;
     /**
      * Restore a persisted session on boot. Validates the stored token with the
      * accelerator; returns the user when valid, or `null` (and clears the
@@ -2231,6 +2245,18 @@ interface HttpClientOptions {
     getSessionToken?: () => string | null;
     /** Custom fetch — defaults to `globalThis.fetch`. */
     fetch?: typeof fetch;
+    /**
+     * Called when a token-gated request comes back `401` (stale/expired
+     * session). Should attempt to silently re-establish a session and resolve
+     * `true` if it succeeded (the request is then retried once with the fresh
+     * token) or `false` if it couldn't (the `401` propagates as an
+     * {@link HttpError}). Wired by {@link Client} to `auth.zk.recover()`.
+     *
+     * Only consulted by the JSON helpers (`get`/`post`/`del`); the raw
+     * {@link fetch} passes 401s straight through so the auth wire calls that
+     * power recovery itself can't recurse.
+     */
+    onUnauthorized?: () => Promise<boolean>;
 }
 /** Thrown for any non-2xx accelerator response. Carries the HTTP status. */
 declare class HttpError extends Error {
@@ -2242,6 +2268,7 @@ declare class HttpClient {
     readonly baseUrl: string;
     private readonly apiKey;
     private readonly getSessionToken;
+    private readonly onUnauthorized;
     private readonly fetchFn;
     constructor(opts: HttpClientOptions);
     /**
@@ -2257,14 +2284,14 @@ declare class HttpClient {
 }
 
 /**
- * `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
@@ -2272,13 +2299,15 @@ declare class HttpClient {
  *
  * 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.
  */
 
-interface StorageNamespaceDeps {
+interface KvNamespaceDeps {
     http: HttpClient;
     session: SessionState;
     /** WebSocket base (ws/wss) for the change feed; derived from baseUrl. */
@@ -2295,11 +2324,11 @@ interface StorageChangeEvent<T = unknown> {
     /** The decrypted value for `set`; `null` for `delete`. */
     data: T | null;
 }
-declare class StorageNamespace {
+declare class KvNamespace {
     private readonly deps;
     private cipher;
     private cipherIdentity;
-    constructor(deps: StorageNamespaceDeps);
+    constructor(deps: KvNamespaceDeps);
     /** Store `value` under `collection`/`id` (encrypted at rest by default). */
     set<T = unknown>(collection: string, id: string, value: T, opts?: SetOptions): Promise<void>;
     /** Fetch the value at `collection`/`id`, or `null` if absent. */
@@ -2328,6 +2357,100 @@ declare class StorageNamespace {
     private getCipher;
 }
 
+/**
+ * `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.
+ */
+
+interface FileNamespaceDeps {
+    http: HttpClient;
+    baseUrl: string;
+    /** Used for the unmetered personal discovery mirror. */
+    kv: KvNamespace;
+    /**
+     * Optional pre-compiled Reed–Solomon WASM module. Defaults to the bundled
+     * loader; pass one where the bundled loader path isn't available (vitest,
+     * deploy-time-precompiled environments). Forwarded to {@link FileStorage}.
+     */
+    rsWasmModule?: WebAssembly.Module;
+}
+interface WriteFileOptions {
+    /** SharedSpace the file is written to (obtain via `client.space`). */
+    spaceId: string;
+    data: Uint8Array | Blob | File;
+    metadata: {
+        name: string;
+        type: string;
+        path?: string;
+        lastModified?: number;
+    };
+}
+declare class StorageNamespace {
+    private readonly deps;
+    private fileStorage;
+    constructor(deps: FileNamespaceDeps);
+    /**
+     * 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).
+     */
+    writeFile(input: WriteFileOptions): Promise<{
+        stat: FileStat;
+        manifest: FileManifest;
+    }>;
+    /** Read a file from its space (resolves the manifest, then the shards). */
+    readFile(spaceId: string, fileId: string): Promise<{
+        data: Uint8Array;
+        stat: FileStat;
+    }>;
+    /**
+     * Read a file straight from a manifest — the capability path. No space
+     * membership needed; this is how a shared file is opened.
+     */
+    readByManifest(manifest: FileManifest): Promise<{
+        data: Uint8Array;
+        stat: FileStat;
+    }>;
+    /**
+     * List files. With no argument, returns the caller's own shared files from
+     * the personal mirror; with `{ spaceId }`, lists that space's files.
+     */
+    listFiles(opts?: {
+        spaceId?: string;
+    }): Promise<FileStat[]>;
+    /** Delete a file from its space and remove the personal mirror entry. */
+    deleteFile(spaceId: string, fileId: string): Promise<boolean>;
+    /** Read a manifest verbatim (e.g. to share a file). */
+    getManifest(spaceId: string, fileId: string): Promise<FileManifest>;
+    private fs;
+    private _shards;
+    private shards;
+    private _space;
+    private space;
+}
+
 /**
  * Shared types for the Space fan-out group-encryption layer.
  *
@@ -2631,8 +2754,35 @@ interface SpaceMessageEvent {
     channel: string;
     epoch: number;
     contentType?: string;
+    /**
+     * Server storage handle — the monotonic server timestamp this message is
+     * persisted under (`msg:<handle>`). Stable across history replay; pass it to
+     * {@link Space.editMessage} / {@link Space.deleteMessage} to mutate the
+     * persisted entry. Carried on edit events too (same handle as the original).
+     */
+    handle: number;
     message: Message;
 }
+/**
+ * An inbound ephemeral signal — an application broadcast the server relays to
+ * the room but never persists (no history). Rides the generic `pub` relay:
+ * `subject` is an app-defined routing key, `data` is opaque app JSON, and
+ * `from` is the server-authenticated sender. Typing indicators, presence pings,
+ * live cursors, etc. are built on top of this in the app layer — the SDK and
+ * server stay domain-agnostic.
+ */
+interface EphemeralEvent {
+    /** Server-stamped authenticated sender. */
+    from: string;
+    /** Application-defined routing key (e.g. "typing"). */
+    subject: string;
+    /** Opaque application payload. */
+    data: unknown;
+}
+/** A server-authoritative deletion of the persisted message at `handle`. */
+interface MessageDeletedEvent {
+    handle: number;
+}
 interface SpaceDeps {
     /** Transport room id. For fan-out spaces this is the encoded space pubkey. */
     name: string;
@@ -2715,6 +2865,38 @@ declare class Space {
     }): Promise<void>;
     /** Subscribe to decrypted fan-out messages. Returns an unsubscribe fn. */
     onMessage(handler: (e: SpaceMessageEvent) => void): () => void;
+    /**
+     * 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.
+     */
+    editMessage(handle: number, payload: unknown, opts?: {
+        channel?: string;
+        contentType?: string;
+    }): Promise<void>;
+    /**
+     * 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.
+     */
+    deleteMessage(handle: number): Promise<void>;
+    /** Subscribe to in-place edits of persisted messages (new content at the same handle). */
+    onMessageEdited(handler: (e: SpaceMessageEvent) => void): () => void;
+    /** Subscribe to deletions of persisted messages. */
+    onMessageDeleted(handler: (e: MessageDeletedEvent) => void): () => void;
+    /**
+     * 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: string, data: unknown): void;
+    /** Subscribe to inbound ephemeral signals. `from` is the authenticated sender. */
+    onEphemeral(handler: (e: EphemeralEvent) => void): () => void;
     /** Subscribe to inbound join requests (for a key-holder to admit). */
     onJoinRequest(handler: (req: JoinRequest) => void): () => void;
     /**
@@ -2759,10 +2941,18 @@ declare class Space {
     /** Wire the RAW_FRAME handler that drives fan-out events. */
     private wireFanout;
     private onRawFrame;
+    /**
+     * 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.
+     */
+    private sealMessage;
     /**
      * 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.
      */
     private decodeFrame;
     /**
@@ -2990,7 +3180,9 @@ declare class Client {
     readonly baseUrl: string;
     /** Authentication — `client.auth.zk.login(...)`, etc. */
     readonly auth: AuthNamespace;
-    /** Per-user persistent storage — `client.storage.set(...)`, etc. */
+    /** Per-user key/value storage — `client.kv.set(...)`, etc. */
+    readonly kv: KvNamespace;
+    /** File storage — `client.storage.writeFile(...)`, etc. */
     readonly storage: StorageNamespace;
     /** Realtime messaging — `client.message.subscribe(...)`, etc. */
     readonly message: MessageNamespace;
@@ -2998,11 +3190,34 @@ declare class Client {
     readonly space: SpaceNamespace;
     private readonly session;
     private readonly http;
+    /** Subscribers notified when a session expires and can't be recovered. */
+    private readonly sessionExpiredHandlers;
+    /** Shared in-flight recovery so a burst of 401s triggers one re-auth. */
+    private recoverInFlight;
     constructor(options?: ClientOptions);
     /** The currently signed-in user, or `null`. */
     get user(): AuthUser | null;
     /** Whether a token-bearing session is active. */
     get isAuthenticated(): boolean;
+    /**
+     * 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: () => void): () => void;
+    /**
+     * 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(): Promise<boolean>;
 }
 
 /**
@@ -3043,5 +3258,5 @@ declare class KeyringClient implements KeyringTransport {
     fetchMetadata(): Promise<SpaceMetadata | null>;
 }
 
-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 type { ACL, ACLEntry, AuthClientOptions, AuthKeyPair, AuthSuccess, AuthToken, AuthType, AuthUser, Bn128WasmInstance, BroadcastChannelEvent, BroadcastChannelOptions, ChannelLike, ChunkKeyMaterial, ChunkManifest, CipherFrame, CipherMessage, CipherMessageHeader, CircuitBufferConfig, CircuitUrls, ClientOptions, DehydratedKeypair, DehydratedKeys, DoubleRatchetCipherDeps, ECDHCurve, EncodeResult, EpochKeyProvider, FileManifest, FileStat, FileStorageOptions, Groth16Proof, HttpClientOptions, IncomingFrame, KeyExchangeFrame, KeyPair, Keypair, KeyringClientDeps, KeyringTransport, LoginOptions, MessageBody, MessageEvent, MessageHeaders, MessageNamespaceDeps, MessageOptions, MessageSubscription, MuhkooMessageEvent, OAuthProvider, PacketCipher, PacketHeaders, PacketOptions, Participant, Permission, PermissionCheckRequest, PermissionCheckResult, PersonalSpaceClientOptions, PublicKeyJWK, RatchetState, ReceiveResult, RegisterParams, Role, SpaceDeps as RoomDeps, SpaceFileMetadata as RoomFileMetadata, SealedHeaders, Session, SessionOptions, SessionStore, SetOptions, ShardClientOptions, SharedSpaceClientOptions, SnarkProof, SpaceChannelLike, SpaceDeps, SpaceFileMetadata, SpaceKeyCache, SpaceKeyringDeps, SpaceMessageEvent, SpaceNamespaceDeps, StorageChangeEvent, StorageNamespaceDeps, StoredSession, Subscription, UserIdentity, VerificationKey, WSMessage, WSMessageType, WSTransportOptions, WrappedPayload, WriteFileInput, WriteToShardsInput, ZkAuthDeps, ZkAuthenticateRequest, ZkChallengeResponse, ZkCompiled, ZkIdentity, ZkRegisterRequest, ZkRegisterResponse };
+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 };
+export type { ACL, ACLEntry, AuthClientOptions, AuthKeyPair, AuthSuccess, AuthToken, AuthType, AuthUser, Bn128WasmInstance, BroadcastChannelEvent, BroadcastChannelOptions, ChannelLike, ChunkKeyMaterial, ChunkManifest, CipherFrame, CipherMessage, CipherMessageHeader, CircuitBufferConfig, CircuitUrls, ClientOptions, DehydratedKeypair, DehydratedKeys, DoubleRatchetCipherDeps, ECDHCurve, EncodeResult, EphemeralEvent, EpochKeyProvider, FileManifest, FileNamespaceDeps, FileStat, FileStorageOptions, Groth16Proof, HttpClientOptions, IncomingFrame, KeyExchangeFrame, KeyPair, Keypair, KeyringClientDeps, KeyringTransport, KvNamespaceDeps, LoginOptions, MessageBody, MessageDeletedEvent, MessageEvent, MessageHeaders, MessageNamespaceDeps, MessageOptions, MessageSubscription, MuhkooMessageEvent, OAuthProvider, PacketCipher, PacketHeaders, PacketOptions, Participant, Permission, PermissionCheckRequest, PermissionCheckResult, PersonalSpaceClientOptions, PublicKeyJWK, RatchetState, ReceiveResult, RegisterParams, Role, SpaceDeps as RoomDeps, SpaceFileMetadata as RoomFileMetadata, SealedHeaders, Session, SessionOptions, SessionStore, SetOptions, ShardClientOptions, SharedSpaceClientOptions, SnarkProof, SpaceChannelLike, SpaceDeps, SpaceFileMetadata, SpaceKeyCache, SpaceKeyringDeps, SpaceMessageEvent, SpaceNamespaceDeps, StorageChangeEvent, StoredSession, Subscription, UserIdentity, VerificationKey, WSMessage, WSMessageType, WSTransportOptions, WrappedPayload, WriteFileInput, WriteFileOptions, WriteToShardsInput, ZkAuthDeps, ZkAuthenticateRequest, ZkChallengeResponse, ZkCompiled, ZkIdentity, ZkRegisterRequest, ZkRegisterResponse };