@muhkoo/connect 0.9.0-alpha.0 → 0.10.0-alpha.0

package/dist/connect.d.ts

@@ -1494,6 +1494,9 @@ declare class ShardClient {
      * `null` for 404 so callers can distinguish "missing" from "errored".
      */
     getShard(hash: string): Promise<Uint8Array | null>;
+    /** Fetch a shard from origin. Returns `null` for 404 (or offline when a
+     *  cache is present, so RS recovery can proceed); throws otherwise. */
+    private fetchFromOrigin;
     /**
      * Check whether a shard exists. Lets the caller skip a PUT they'd otherwise
      * dedup-rewrite. The server can implement this as a HEAD or return a small
@@ -2511,6 +2514,21 @@ declare class ZkAuth {
      * to re-enable encryption/messaging without a full re-login.
      */
     restore(): Promise<AuthUser | null>;
+    /**
+     * Boot helper — call this once on app start. Restores the session AND, when a
+     * passkey is enrolled, silently unlocks the identity via WebAuthn (recovering
+     * the master seed so the ratchet keypair rehydrates and `client.kv` works).
+     * The seed is never persisted, so a passkey (or password) is the only way to
+     * unlock after a reload — this keeps that off the app's plate.
+     *
+     * Returns `{ user, unlocked }`. When `unlocked` is false (no passkey, the
+     * user cancelled, or the browser required a gesture), prompt for a password
+     * and call {@link unlock}. Apps need no key-management scaffolding beyond this.
+     */
+    resume(): Promise<{
+        user: AuthUser | null;
+        unlocked: boolean;
+    }>;
     /**
      * Re-derive identity material for an already-authenticated (restored)
      * session, so the client can decrypt storage and run the ratchet. Verifies
@@ -3723,11 +3741,29 @@ declare class SpaceKeyring implements EpochKeyProvider {
     private readonly policy;
     /** Cached member directory: memberId → imported ECDSA verify key. */
     private readonly memberEcdsa;
+    /** Coalesce concurrent roster refreshes (the parallel history/backlog decode
+     *  would otherwise fire one `roster` fetch PER message — a thundering herd). */
+    private dirInFlight;
+    private dirRefreshedAt;
+    /** Min gap between non-forced roster refreshes. A miss that persists within
+     *  this window won't re-fetch (the roster hasn't changed that fast); genuine
+     *  membership changes use `{ force: true }` (join requests / history loads). */
+    private static readonly DIR_COOLDOWN_MS;
     constructor(deps: SpaceKeyringDeps);
     /** The cached ECDSA verify key for a member, if known. */
     ecdsaKeyFor(memberId: string): CryptoKey | undefined;
-    /** Refresh the member directory (memberId → ECDSA key) from the roster. */
-    refreshDirectory(): Promise<void>;
+    /**
+     * Refresh the member directory (memberId → ECDSA key) from the roster.
+     * Coalesces concurrent callers into ONE fetch, and skips a fetch when one
+     * completed within {@link DIR_COOLDOWN_MS} (unless `force`). Without this, a
+     * page of N messages decoded in parallel — each missing the cold directory —
+     * fires N simultaneous `roster` requests that queue behind the browser's
+     * connection limit and take many seconds.
+     */
+    refreshDirectory(opts?: {
+        force?: boolean;
+    }): Promise<void>;
+    private doRefreshDirectory;
     currentEpoch(): number;
     keyForEpoch(epoch: number): Uint8Array | undefined;
     hasAnyKey(): boolean;
@@ -3748,6 +3784,13 @@ declare class SpaceKeyring implements EpochKeyProvider {
      * epoch keys obtained. Safe to call repeatedly (idempotent).
      */
     pullKeys(): Promise<number>;
+    /**
+     * Background freshness check for the cache-hit fast path: confirm we hold the
+     * current epoch (picks up a rotation / our removal) WITHOUT the full newcomer
+     * admit handshake. Cheap + idempotent; never blocks first paint. Returns the
+     * number of newly-obtained epoch keys (0 = already current).
+     */
+    reconcile(): Promise<number>;
     /**
      * Wrap our group key(s) for a newcomer and post the blobs. In a `static`
      * space the newcomer receives every epoch we hold (full history); in a
@@ -4207,6 +4250,53 @@ declare class MessageNamespace {
     private myId;
 }
 
+/**
+ * `ChatKeyVault` — SDK-owned lifecycle for a member's long-lived ratchet/space
+ * keypair (the connect `KeyStore` entry keyed by the member id / username).
+ *
+ * Historically each app hand-rolled this (see the web app's old
+ * `personal/spaceLoader.ts`): generate a keypair at register, seed-wrap it, and
+ * PUT it to the personal space; on login GET + unwrap + hydrate the `KeyStore`.
+ * That scaffolding now lives here so ANY app gets a **stable** member keypair
+ * across reloads for free — without which the member re-admits to every space on
+ * every load and the group-key cache can never round-trip.
+ *
+ * Security invariant: the wrapping secret is the **master seed** (not the
+ * password), so the blob survives password changes and unlocks under a passkey.
+ * The seed is only ever held in memory (never persisted), so this vault can only
+ * provision/rehydrate while the client is unlocked.
+ */
+
+/** Opaque personal-space blob store (a `PersonalSpaceClient` or a kv-backed shim). */
+interface ChatKeyStore {
+    get(key: string): Promise<WrappedPayload | null>;
+    put(key: string, value: WrappedPayload): Promise<void>;
+}
+declare class ChatKeyVault {
+    private readonly store;
+    constructor(store: ChatKeyStore);
+    /**
+     * Register-time: ensure a keypair exists for `memberId`, seed-wrap the
+     * dehydrated form, and persist it to the personal space. Idempotent — reuses
+     * an existing in-tab keypair rather than minting a second one.
+     */
+    provision(memberId: string, seedSecret: string): Promise<void>;
+    /**
+     * Sign-in / unlock time: fetch the wrapped blob, unwrap with the seed, and
+     * hydrate the `KeyStore` — restoring the SAME keypair the member had before.
+     * Returns `true` when a keypair is now in hand (already present or hydrated),
+     * `false` when there's no blob yet (a brand-new member → caller provisions).
+     * Throws only on a genuine unwrap failure (wrong secret / tampered blob).
+     */
+    rehydrate(memberId: string, seedSecret: string): Promise<boolean>;
+    /**
+     * Ensure a stable keypair is in hand: rehydrate from the vault if a blob
+     * exists, otherwise mint one and persist it (so it's stable next session).
+     * Used at register and lazily when a space is first opened.
+     */
+    ensure(memberId: string, seedSecret: string): Promise<void>;
+}
+
 /**
  * `client.space` — the fan-out group-encryption surface.
  *
@@ -4242,6 +4332,9 @@ interface SpaceNamespaceDeps {
     cache?: SpaceKeyCache;
     /** Offline manager — enables message caching + offline send replay. */
     offline?: OfflineManager;
+    /** SDK-owned ratchet-keypair vault — gives a STABLE member keypair across
+     *  reloads (rehydrate-or-provision) instead of a fresh one each session. */
+    chatKeys?: ChatKeyVault;
     /** P2P swarm config — enables peer block exchange among Space members. */
     p2p?: {
         enabled?: boolean;
@@ -4249,6 +4342,7 @@ interface SpaceNamespaceDeps {
         workerFactory?: () => Worker;
         iceServers?: RTCIceServer[];
         maxPeers?: number;
+        debug?: boolean;
     };
 }
 declare class SpaceNamespace {
@@ -4727,6 +4821,8 @@ interface ClientOptions {
         workerFactory?: () => Worker;
         iceServers?: RTCIceServer[];
         maxPeers?: number;
+        /** Log P2P mesh + block-exchange activity to the console (staging/dev). */
+        debug?: boolean;
     };
 }
 declare class Client {
@@ -5245,10 +5341,13 @@ interface EngineHandle {
 interface PeerExchangeOptions {
     /** How long to wait for a peer before giving up to origin. Default 2500ms. */
     timeoutMs?: number;
+    /** Log peer-served vs origin-fallback per block to the console. */
+    debug?: boolean;
 }
 declare class PeerExchange implements PeerBlockSource {
     private readonly engine;
     private readonly timeoutMs;
+    private readonly debug;
     constructor(engine: EngineHandle, opts?: PeerExchangeOptions);
     getBlock(hash: string, opts?: {
         timeoutMs?: number;
@@ -5404,6 +5503,8 @@ interface PeerNetworkOptions {
     timeoutMs?: number;
     /** Inject a transport (tests / a future libp2p transport). Default WebRTC. */
     transport?: PeerTransport;
+    /** Log mesh + block-exchange activity to the console (use on staging/dev). */
+    debug?: boolean;
 }
 declare class PeerNetwork {
     /** Pass this to a `ShardClient` as `peers`. */