@muhkoo/connect 0.1.0-alpha.2 → 0.2.0-alpha.2

package/dist/connect.d.ts

@@ -2329,75 +2329,452 @@ declare class StorageNamespace {
 }
 
 /**
- * `Room` — a client handle for one shared space (a chat-style room).
+ * Shared types for the Space fan-out group-encryption layer.
  *
- * A shared space carries two things, and `Room` exposes both:
- *   - **realtime E2E messaging** over a {@link BroadcastChannel} (group
- *     handshake, ratchet send/receive, roster frames);
- *   - **room-scoped file storage** via {@link FileStorage} over the room's
- *     shard endpoint.
+ * A Space is a group channel whose messages are sealed once with a symmetric
+ * group key (`K_space`) rather than per-peer like the Double Ratchet. That
+ * single ciphertext is decryptable by every member that holds the epoch key,
+ * which is what lets the server persist + replay messages as history while
+ * staying blind to their contents.
+ */
+/**
+ * How a space treats history across membership changes.
+ *  - `static`: one group key for all time (epoch 0). New members can read the
+ *    entire history; a removed member keeps the key until you rotate manually.
+ *  - `rotate`: a new epoch key is minted on membership change. Members only
+ *    hold keys for the epochs they belonged to, so they cannot read messages
+ *    from epochs before they joined / after they left.
+ */
+type HistoryPolicy = "static" | "rotate";
+/**
+ * An ECIES-wrapped copy of a group key, sealed to one member's identity ECDH
+ * public key. Opaque to the server — useless without the member's private key.
+ */
+interface WrappedKey {
+    /** Epoch this key belongs to (0 for static spaces). */
+    epoch: number;
+    /** Base64url-encoded JWK of the ephemeral ECDH public key used for the wrap. */
+    ephemeralPub: string;
+    /** Base64 AES-GCM IV (12 bytes). */
+    iv: string;
+    /** Base64 AES-GCM ciphertext: the wrapped 32-byte group key + tag. */
+    ciphertext: string;
+    /** Algorithm tag for forward-compat. */
+    alg: string;
+}
+/** Cleartext space metadata the server records once at creation. */
+interface SpaceMetadata {
+    /** Encoded space public key (the space's logical identity). */
+    spaceId: string;
+    historyPolicy: HistoryPolicy;
+    /** Advisory monotonic epoch counter. */
+    currentEpoch: number;
+}
+/**
+ * A newcomer's request for the group key. The newcomer self-asserts its
+ * identity public keys (trust-on-first-use at the client layer; the server is
+ * blind and cannot validate them).
+ */
+interface JoinRequest {
+    memberId: string;
+    /** Base64url-encoded JWK of the member's identity ECDH public key. */
+    identityEcdhPub: string;
+    /** Base64url-encoded JWK of the member's identity ECDSA public key (optional). */
+    identityEcdsaPub?: string;
+    /** Epoch the newcomer wants a key for (defaults to current). */
+    desiredEpoch?: number;
+    ts?: number;
+}
+/** A space member's published identity keys (the keyring directory). */
+interface RosterMember {
+    memberId: string;
+    /** Base64url-encoded JWK of the member's identity ECDH public key. */
+    identityEcdhPub: string;
+    /** Base64url-encoded JWK of the member's identity ECDSA public key. */
+    identityEcdsaPub?: string;
+}
+
+/**
+ * PacketCipher — the strategy `Network` uses to seal/open a packet's payload.
  *
- * Obtained from `client.message.room(name)`. The websocket isn't opened until
- * `connect()` — and `putFile`/`getFile` don't need it at all (they're plain
- * shard HTTP), so reading a shared file never opens a socket. The upgrade
- * ticket + identity are resolved lazily inside `connect()`.
+ * `Network` owns the wire shape (Message ↔ Packet, header placement, transport,
+ * reconnect, checksum). The *encryption* is pluggable: the default
+ * {@link DoubleRatchetCipher} reproduces the per-peer Double Ratchet behavior
+ * Network has always had, while the Space layer supplies a group-key cipher.
  *
- * `Room` intentionally mirrors the `BroadcastChannel` surface the chat hook
- * already uses (`on`/`off`/`send`/`sendRaw`/`announce`/`peers`/`isConnected`)
- * so adopting it is a drop-in swap for `new BroadcastChannel(...)`.
+ * The sealed ciphertext always rides in `Packet.headers` (cleartext routing
+ * fields stay readable to the server); `Packet.message` is left undefined on
+ * the wire so the server never sees the real payload.
+ */
+
+type PacketHeaders = Packet["headers"];
+/** Header fields a cipher merges into the outgoing packet. */
+type SealedHeaders = Record<string, string | number | boolean>;
+interface PacketCipher {
+    /**
+     * Seal the serialized `Message`. Returns the header fields to merge into
+     * the outgoing packet (these carry the ciphertext). `Network` clears
+     * `packet.message` after calling this.
+     */
+    seal(serializedMessage: string, packet: Packet): Promise<SealedHeaders>;
+    /** True if the inbound headers look like this cipher's sealed form. */
+    handles(headers: PacketHeaders): boolean;
+    /**
+     * Open an inbound packet's headers back into a serialized `Message` string.
+     * Returns `null` when the packet is not sealed for / not decryptable by us
+     * (e.g. an epoch key we don't hold) — `Network` then leaves `packet.message`
+     * untouched rather than throwing.
+     */
+    open(headers: PacketHeaders): Promise<string | null>;
+}
+interface DoubleRatchetCipherDeps {
+    ratchetManager: DoubleRatchetManager;
+    clientId: string;
+    serverId: string;
+    sessionType: "global" | "specific";
+    /** Resolves the live session id (Network manages the session lifecycle). */
+    getSessionId: () => string | null;
+    /** Whether this side is the ratchet "client" (default true). */
+    isClient?: boolean;
+}
+/**
+ * Default cipher: per-peer Double Ratchet. Reproduces Network's original
+ * `{ encrypted: true, cipherMessage: <json> }` header convention exactly so
+ * existing consumers are unaffected.
+ */
+declare class DoubleRatchetCipher implements PacketCipher {
+    private readonly deps;
+    constructor(deps: DoubleRatchetCipherDeps);
+    seal(serializedMessage: string): Promise<SealedHeaders>;
+    handles(headers: PacketHeaders): boolean;
+    open(headers: PacketHeaders): Promise<string | null>;
+}
+
+/**
+ * SpacePacketCipher — the {@link PacketCipher} that seals packets with a
+ * space's group key instead of a per-peer Double Ratchet.
+ *
+ * It pulls the active epoch's key from an {@link EpochKeyProvider} (the
+ * SpaceKeyring), so this adapter stays decoupled from the keyring's transport
+ * and caching concerns — it only needs "what key seals epoch N".
+ */
+
+/** Minimal view of the keyring the cipher needs. */
+interface EpochKeyProvider {
+    /** Epoch new messages are sealed under (advances on rotation). */
+    currentEpoch(): number;
+    /** The 32-byte group key for an epoch, or undefined if we don't hold it. */
+    keyForEpoch(epoch: number): Uint8Array | undefined;
+}
+declare class SpacePacketCipher implements PacketCipher {
+    private readonly keys;
+    private readonly contentType?;
+    constructor(keys: EpochKeyProvider, contentType?: string | undefined);
+    seal(serializedMessage: string): Promise<SealedHeaders>;
+    handles(headers: PacketHeaders): boolean;
+    /** Returns null for epochs we don't hold (surfaced as undecryptable). */
+    open(headers: PacketHeaders): Promise<string | null>;
+}
+
+/**
+ * SpaceKeyring — the client's view of a space's group keys.
+ *
+ * Holds the per-epoch group keys this member possesses (in memory, optionally
+ * mirrored to PersonalSpace), and orchestrates the server-blind distribution
+ * dance against a {@link KeyringTransport}:
+ *
+ *   - a newcomer posts a join request and pulls the wrapped key blob addressed
+ *     to it, unwrapping with its identity private key;
+ *   - an existing key-holder wraps the group key for a newcomer (ECIES to the
+ *     newcomer's identity public key) and posts the opaque blob;
+ *   - on membership change (rotate spaces) a fresh epoch key is minted and
+ *     re-wrapped to the current roster.
+ *
+ * The server only ever stores opaque {@link WrappedKey} blobs — it cannot read
+ * the group key. Implements {@link EpochKeyProvider} so it can back a
+ * {@link SpacePacketCipher} directly.
+ */
+
+/**
+ * Reserved member id for the app's "keeper" — a trusted always-available member
+ * (the accelerator's AppDOv1) that holds the group key and re-issues it to
+ * newcomers, so a channel is joinable with no human online. Admitting this id
+ * at channel creation hands the key to the keeper. MUST match the accelerator's
+ * `KEEPER_MEMBER_ID`.
+ */
+declare const KEEPER_MEMBER_ID = "__keeper__";
+/** Opaque-blob transport to the space's keyring (HTTP or in-memory test seam). */
+interface KeyringTransport {
+    postJoinRequest(req: JoinRequest): Promise<void>;
+    /** All wrapped blobs addressed to `memberId` (any epoch). */
+    fetchBlobs(memberId: string): Promise<WrappedKey[]>;
+    /** Post a wrapped key blob for `targetMemberId`. */
+    postWrappedKey(targetMemberId: string, wrapped: WrappedKey, fromMemberId: string): Promise<void>;
+    /** Outstanding join requests (for an online key-holder to fulfill). */
+    fetchPending(): Promise<JoinRequest[]>;
+    /** Current roster: member ids + their identity ECDH/ECDSA public keys. */
+    fetchRoster(): Promise<RosterMember[]>;
+    /** Advisory epoch bump; returns the agreed new epoch. */
+    rotate(nextEpoch: number): Promise<{
+        epoch: number;
+    }>;
+    /** Add `username` to a private channel's membership allowlist. */
+    invite(username: string): Promise<void>;
+    fetchMetadata(): Promise<SpaceMetadata | null>;
+}
+/** PersonalSpace-backed cache of this member's group keys (epoch → base64 key). */
+interface SpaceKeyCache {
+    loadKeys(spaceId: string): Promise<Record<string, string> | null>;
+    saveKeys(spaceId: string, keys: Record<string, string>): Promise<void>;
+}
+interface SpaceKeyringDeps {
+    spaceId: string;
+    memberId: string;
+    /** This member's identity ECDH public key, base64url JWK (for join requests). */
+    identityEcdhPub: string;
+    /** This member's identity ECDSA public key, base64url JWK (published for
+     * sender-signature verification). */
+    identityEcdsaPub?: string;
+    /** Resolves this member's identity ECDH private key (for unwrapping). */
+    ownPrivateKey: () => CryptoKey | null;
+    transport: KeyringTransport;
+    cache?: SpaceKeyCache;
+    historyPolicy?: HistoryPolicy;
+}
+declare class SpaceKeyring implements EpochKeyProvider {
+    private readonly deps;
+    private readonly keys;
+    private epoch;
+    private readonly policy;
+    /** Cached member directory: memberId → imported ECDSA verify key. */
+    private readonly memberEcdsa;
+    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>;
+    currentEpoch(): number;
+    keyForEpoch(epoch: number): Uint8Array | undefined;
+    hasAnyKey(): boolean;
+    /** Hydrate keys from the PersonalSpace cache, if available. Best-effort —
+     * a cache miss/failure (e.g. not unlocked) must not block joining. */
+    loadFromCache(): Promise<boolean>;
+    private persist;
+    /** Creator path: mint epoch-0 group key for a brand-new space. */
+    bootstrapNew(): Promise<void>;
+    /**
+     * Post a join request so an online key-holder can wrap a key for us. Also
+     * publishes our identity keys in the member directory (so others can verify
+     * our message signatures, and the keeper can wrap to us).
+     */
+    requestKey(desiredEpoch?: number): Promise<void>;
+    /**
+     * Pull and unwrap any blobs addressed to us. Returns the number of new
+     * epoch keys obtained. Safe to call repeatedly (idempotent).
+     */
+    pullKeys(): 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
+     * `rotate` space they receive only the current epoch.
+     */
+    admit(targetMemberId: string, identityEcdhPub: string): Promise<void>;
+    /**
+     * Admit every outstanding join request (an online key-holder fulfilling
+     * pending newcomers). Returns the ids admitted.
+     */
+    admitPending(): Promise<string[]>;
+    /**
+     * Rotate to a fresh epoch (rotate spaces). Mints a new group key, advances
+     * the epoch, and re-wraps it to every member in `roster` (plus ourselves).
+     */
+    rotate(roster?: Array<{
+        memberId: string;
+        identityEcdhPub: string;
+    }>): Promise<number>;
+    /** Add `username` to a private channel's membership allowlist (member-only). */
+    invite(username: string): Promise<void>;
+}
+
+/**
+ * `Space` — a client handle for one shared space.
+ *
+ * A space is the unit everything is built on. It carries:
+ *   - **realtime transport** over a {@link BroadcastChannel} (group handshake,
+ *     roster frames, raw-frame passthrough);
+ *   - **fan-out group messaging** — `Message`s sealed once with the space's
+ *     group key (via {@link SpacePacketCipher}), wrapped in a cleartext
+ *     {@link Packet} envelope, broadcast AND persisted by the server as
+ *     history (the `spaceMessage` frame);
+ *   - **room-scoped file storage** via {@link FileStorage} over the shard
+ *     endpoint;
+ *   - **legacy per-peer Double Ratchet messaging** (`send`/`announce`) for the
+ *     ephemeral, no-history path — unchanged so existing callers (the chat hook
+ *     reached via `client.message.room(name)`) keep working.
+ *
+ * `Space` was formerly `Room`; `Room` remains exported as an alias. The
+ * fan-out methods (`sendMessage`/`onMessage`/`history`/`join`/`admit`/`rotate`)
+ * require a {@link SpaceKeyring} dep; without one only the transport + DR +
+ * file surface is available.
  */
 
 type Listener = (e: CustomEvent) => void;
-interface RoomFileMetadata {
+interface SpaceFileMetadata {
     name: string;
     type: string;
     path?: string;
     lastModified?: number;
 }
-interface RoomDeps {
+/** A decrypted inbound fan-out message. */
+interface SpaceMessageEvent {
+    from: string;
+    channel: string;
+    epoch: number;
+    contentType?: string;
+    message: Message;
+}
+interface SpaceDeps {
+    /** Transport room id. For fan-out spaces this is the encoded space pubkey. */
     name: string;
     wsBaseUrl: string;
     httpBaseUrl: string;
     /** Header-injecting fetch from the client's HttpClient. */
     fetch: typeof fetch;
-    /** Resolves the user id used for the ratchet (the signed-in username). */
+    /** Resolves the user id used for the ratchet / member id (signed-in username). */
     myId: () => string;
     /** Resolves a short-lived WS upgrade ticket (or null when keyless). */
     fetchTicket: () => Promise<string | null>;
+    /** Optional group-key keyring — required for the fan-out methods. */
+    keyring?: SpaceKeyring;
+    /** History policy for this space (advisory; defaults to static). */
+    historyPolicy?: HistoryPolicy;
+    /**
+     * When true (default), a connected member that holds the group key
+     * automatically wraps it for any newcomer that posts a join request —
+     * the "any online key-holder admits" model. Set false to gate membership
+     * yourself via `onJoinRequest` + `admit`.
+     */
+    autoAdmit?: boolean;
+    /**
+     * Test seam — defaults to constructing a real {@link BroadcastChannel}.
+     * A test can inject an in-memory channel to exercise the fan-out wire
+     * without a live websocket.
+     */
+    createChannel?: (url: string, myId: string) => SpaceChannelLike;
+}
+/** The subset of {@link BroadcastChannel} a {@link Space} drives. */
+interface SpaceChannelLike {
+    on(event: string, handler: (e: CustomEvent) => void): void;
+    off(event: string, handler: (e: CustomEvent) => void): void;
+    connect(): Promise<void>;
+    disconnect(): void;
+    announce(): Promise<void>;
+    send(plaintext: string): Promise<number>;
+    sendRaw(frame: unknown): void;
+    peers?(): string[];
+    isConnected?(): boolean;
 }
-declare class Room {
+declare class Space {
     private readonly deps;
     readonly name: string;
+    readonly historyPolicy: HistoryPolicy;
     private channel;
     private readonly pending;
-    constructor(deps: RoomDeps);
-    /** Open the room websocket (resolves the ticket + identity lazily). */
+    private readonly cipher;
+    /** Per-instance event bus for fan-out events (isolated across spaces). */
+    private readonly events;
+    private rawWired;
+    constructor(deps: SpaceDeps);
+    /** The encoded space id (same as the transport name for fan-out spaces). */
+    get id(): string;
+    /** The keyring backing this space's group keys, if any. */
+    get keyring(): SpaceKeyring | undefined;
+    /** Open the space websocket (resolves the ticket + identity lazily). */
     connect(): Promise<void>;
     disconnect(): void;
-    /** Subscribe to a channel event. Buffered until `connect()` if early. */
+    /** Subscribe to a raw channel event. Buffered until `connect()` if early. */
     on(event: string, handler: Listener): void;
     off(event: string, handler: Listener): void;
     /** Advertise our keyExchange to the room (idempotent per connection). */
     announce(): Promise<void>;
-    /** E2E-encrypt `text` to every peer; returns the recipient count. */
+    /** E2E-encrypt `text` to every peer via the Double Ratchet (no history). */
     send(text: string): Promise<number>;
     /** Send an arbitrary JSON frame (e.g. the `{name}` handshake). */
     sendRaw(frame: unknown): void;
     peers(): string[];
     isConnected(): boolean;
     /** The underlying channel, for advanced use. `null` before `connect()`. */
-    get raw(): BroadcastChannel | null;
-    /** Encrypt + erasure-code + upload `file` to this room's shards. */
-    putFile(file: File | Blob | Uint8Array, metadata: RoomFileMetadata): Promise<{
+    get raw(): SpaceChannelLike | null;
+    /**
+     * Seal `payload` once with the current group key and broadcast it as a
+     * persisted `spaceMessage`. Requires a keyring.
+     */
+    sendMessage(payload: unknown, opts?: {
+        channel?: string;
+        contentType?: string;
+    }): Promise<void>;
+    /** Subscribe to decrypted fan-out messages. Returns an unsubscribe fn. */
+    onMessage(handler: (e: SpaceMessageEvent) => void): () => void;
+    /** Subscribe to inbound join requests (for a key-holder to admit). */
+    onJoinRequest(handler: (req: JoinRequest) => void): () => void;
+    /**
+     * Fetch + decrypt persisted history beyond the live backlog.
+     * `before` is an opaque cursor returned as `nextCursor`.
+     */
+    history(opts?: {
+        before?: string;
+        limit?: number;
+    }): Promise<{
+        messages: SpaceMessageEvent[];
+        nextCursor: string | null;
+    }>;
+    /**
+     * Bring this member's group keys up to date: load from cache, and if we
+     * hold nothing, request a key and poll until one arrives (or timeout).
+     */
+    join(opts?: {
+        timeoutMs?: number;
+        pollMs?: number;
+    }): Promise<boolean>;
+    /** Creator path: mint the initial group key, then connect. */
+    create(): Promise<void>;
+    /** Wrap the group key for a newcomer and post it (key-holder action). */
+    admit(memberId: string, identityEcdhPub: string): Promise<void>;
+    /** Invite a user to this (private) channel's membership allowlist. */
+    invite(username: string): Promise<void>;
+    /** Rotate to a fresh epoch and re-wrap to the roster (rotate spaces). */
+    rotate(roster?: Array<{
+        memberId: string;
+        identityEcdhPub: string;
+    }>): Promise<number>;
+    putFile(file: File | Blob | Uint8Array, metadata: SpaceFileMetadata): Promise<{
         manifest: FileManifest;
         stat: FileStat;
     }>;
-    /** Fetch + decode a file previously shared in this room. */
     getFile(manifest: FileManifest): Promise<{
         data: Uint8Array;
         stat: FileStat;
     }>;
     private fileStorage;
+    /** Wire the RAW_FRAME handler that drives fan-out events. */
+    private wireFanout;
+    private onRawFrame;
+    /**
+     * 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.
+     */
+    private decodeFrame;
+    /**
+     * True if `packet` carries a valid signature by `source`'s identity key.
+     * On a directory cache miss, refresh once (a new member may have just
+     * joined) before giving up. Without a keyring (legacy handle) there's
+     * nothing to verify against → reject.
+     */
+    private verifySender;
+    private emitEvent;
+    private requireKeyring;
+    private requireCipher;
 }
 
 /**
@@ -2484,7 +2861,7 @@ declare class MessageNamespace {
      * primitive group chat is built on (`publish`/`subscribe`/`send` are the
      * higher-level conveniences layered over the same space transport).
      */
-    room(roomName: string): Room;
+    room(roomName: string): Space;
     /** Close every open room connection (e.g. on logout). */
     disconnect(): void;
     private getRoom;
@@ -2494,6 +2871,88 @@ declare class MessageNamespace {
     private myId;
 }
 
+/**
+ * `client.space` — the fan-out group-encryption surface.
+ *
+ *   const space = await client.space.createSpace({ historyPolicy: "static" });
+ *   await space.sendMessage({ text: "hello" });
+ *   space.onMessage(e => …);
+ *
+ *   const joined = await client.space.joinSpace(space.id); // newcomer
+ *
+ * A space owns a client-generated keypair whose public key is its id, a
+ * symmetric group key distributed server-blind via the keyring, and a
+ * persisted message log. This namespace wires the {@link Space} handle to the
+ * HTTP {@link KeyringClient}, the member's identity keys (from {@link KeyStore},
+ * shared with the Double Ratchet path), and a PersonalSpace-backed key cache.
+ */
+
+/** Thrown by `joinChannel` when no channel with that name is registered. */
+declare class ChannelNotFoundError extends Error {
+    readonly channelName: string;
+    constructor(channelName: string);
+}
+/** Thrown by `createChannel` when the name is already registered. */
+declare class ChannelExistsError extends Error {
+    readonly channelName: string;
+    constructor(channelName: string);
+}
+interface SpaceNamespaceDeps {
+    http: HttpClient;
+    session: SessionState;
+    /** WebSocket base (ws/wss); derived from the accelerator baseUrl. */
+    wsBaseUrl: string;
+    /** Optional PersonalSpace-backed cache of group keys (encrypted at rest). */
+    cache?: SpaceKeyCache;
+}
+declare class SpaceNamespace {
+    private readonly deps;
+    constructor(deps: SpaceNamespaceDeps);
+    /**
+     * Create a new space: generate its keypair (public key = id), register
+     * metadata, mint the initial group key, and connect. Returns the open Space.
+     */
+    createSpace(opts?: {
+        historyPolicy?: HistoryPolicy;
+        private?: boolean;
+    }): Promise<Space>;
+    /** Join an existing space by id (its public key). Resolves once a key arrives. */
+    joinSpace(spaceId: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<Space>;
+    /** A handle to a space without auto-connecting (uses cached keys on demand). */
+    get(spaceId: string, historyPolicy?: HistoryPolicy): Promise<Space>;
+    /** List this app's channels (name → space-id) for the key's environment. */
+    listChannels(): Promise<Array<{
+        name: string;
+        spaceId: string;
+    }>>;
+    /** Resolve a channel name to its space id, or null if it doesn't exist. */
+    resolveChannel(name: string): Promise<string | null>;
+    /**
+     * Create a new channel: mint a fan-out space (the caller becomes its first
+     * key-holder) and register `name → spaceId` in the app directory. Throws
+     * {@link ChannelExistsError} if the name is already taken.
+     */
+    createChannel(name: string, opts?: {
+        historyPolicy?: HistoryPolicy;
+        private?: boolean;
+    }): Promise<Space>;
+    /**
+     * Join an existing channel by name. Throws {@link ChannelNotFoundError} if
+     * no channel with that name is registered (use {@link createChannel} first).
+     */
+    joinChannel(name: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<Space>;
+    private build;
+    /** Ensure the member has an identity keypair; return its public ECDH + ECDSA keys. */
+    private ensureIdentity;
+    private fetchPolicy;
+    private fetchTicket;
+    private myId;
+}
+
 /** The hosted Muhkoo Accelerator — the default {@link ClientOptions.baseUrl}. */
 declare const DEFAULT_BASE_URL = "https://api.muhkoo.dev";
 interface ClientOptions {
@@ -2535,6 +2994,8 @@ declare class Client {
     readonly storage: StorageNamespace;
     /** Realtime messaging — `client.message.subscribe(...)`, etc. */
     readonly message: MessageNamespace;
+    /** Fan-out group spaces — `client.space.createSpace(...)`, etc. */
+    readonly space: SpaceNamespace;
     private readonly session;
     private readonly http;
     constructor(options?: ClientOptions);
@@ -2544,5 +3005,43 @@ declare class Client {
     get isAuthenticated(): boolean;
 }
 
-export { AES_GCM_IV_BYTES, AES_GCM_KEY_BYTES, AES_GCM_TAG_BYTES, AuthClient, AuthNamespace, AuthPublicInput, Authenticator, BroadcastChannel, BroadcastChannelEvents, ChunkCipher, Client, DEFAULT_BASE_URL, DoubleRatchet, DoubleRatchetManager, EncryptedSession, EventCore, EventCoreEvents, Field, Field as FieldElement, FileStorage, HashKnowledge, HttpClient, HttpError, KeyStore, LocalStorageSessionStore, MemorySessionStore, Message, Message as MessageDefault, MessageNamespace, PBKDF2_DEFAULT_ITERATIONS, PREIMAGE_POK_VERIFICATION_KEY, Packet, PersonalSpaceClient, Poseidon, PreimagePoK, ReedSolomonCodec, Room, SerializeMessage, SessionState, ShardClient, SharedSpaceClient, 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, ECDHCurve, EncodeResult, FileManifest, FileStat, FileStorageOptions, Groth16Proof, HttpClientOptions, IncomingFrame, KeyExchangeFrame, KeyPair, Keypair, LoginOptions, MessageBody, MessageEvent, MessageHeaders, MessageNamespaceDeps, MessageOptions, MessageSubscription, MuhkooMessageEvent, OAuthProvider, PacketOptions, Participant, Permission, PermissionCheckRequest, PermissionCheckResult, PersonalSpaceClientOptions, PublicKeyJWK, RatchetState, ReceiveResult, RegisterParams, Role, RoomDeps, RoomFileMetadata, Session, SessionOptions, SessionStore, SetOptions, ShardClientOptions, SharedSpaceClientOptions, SnarkProof, StorageChangeEvent, StorageNamespaceDeps, StoredSession, Subscription, UserIdentity, VerificationKey, WSMessage, WSMessageType, WSTransportOptions, WrappedPayload, WriteFileInput, WriteToShardsInput, ZkAuthDeps, ZkAuthenticateRequest, ZkChallengeResponse, ZkCompiled, ZkIdentity, ZkRegisterRequest, ZkRegisterResponse };
+/**
+ * KeyringClient — HTTP implementation of {@link KeyringTransport} against the
+ * accelerator's per-space keyring endpoints. All blobs are opaque to the
+ * server; this client just moves them.
+ *
+ *   POST /api/spaces/:id/keyring/join-request   { ...JoinRequest }
+ *   GET  /api/spaces/:id/keyring/blobs/:member  -> WrappedKey[]
+ *   POST /api/spaces/:id/keyring/wrap           { targetMemberId, fromMemberId, wrapped }
+ *   GET  /api/spaces/:id/keyring/pending        -> JoinRequest[]
+ *   GET  /api/spaces/:id/keyring/roster         -> { memberId, identityEcdhPub }[]
+ *   POST /api/spaces/:id/keyring/rotate         { nextEpoch } -> { epoch }
+ *   GET  /api/spaces/:id/metadata               -> SpaceMetadata
+ */
+
+interface KeyringClientDeps {
+    spaceId: string;
+    httpBaseUrl: string;
+    /** Header-injecting fetch from the client's HttpClient. */
+    fetch: typeof fetch;
+}
+declare class KeyringClient implements KeyringTransport {
+    private readonly deps;
+    constructor(deps: KeyringClientDeps);
+    private url;
+    private post;
+    private get;
+    postJoinRequest(req: JoinRequest): Promise<void>;
+    fetchBlobs(memberId: string): Promise<WrappedKey[]>;
+    postWrappedKey(targetMemberId: string, wrapped: WrappedKey, fromMemberId: string): Promise<void>;
+    fetchPending(): Promise<JoinRequest[]>;
+    fetchRoster(): Promise<RosterMember[]>;
+    rotate(nextEpoch: number): Promise<{
+        epoch: number;
+    }>;
+    invite(username: string): Promise<void>;
+    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 };