@muhkoo/connect 0.1.0-alpha.1

package/dist/connect.d.ts

@@ -0,0 +1,2548 @@
+/**
+ * @public
+ * @remarks
+ * The body type is a generic type that can be any value. Internally we handle the serialization and deserialization of the body.
+ */
+type MessageBody = any;
+/**
+ * @public
+ * @remarks
+ * The message headers type is a simple record object that contains key value pairs. Think of these as metadata for the message, similar to HTTP headers.
+ */
+type MessageHeaders = Map<string, string>;
+/**
+ * @public
+ * @remarks
+ * The message options type is a record object that contains the options for the message.
+ */
+interface MessageOptions {
+    id?: string;
+    body: MessageBody;
+    status?: "pending" | "processed" | "failed" | "delivered";
+    checksum?: string;
+}
+/**
+ * @public
+ * @remarks
+ * The message class is a simple class that represents a message object.
+ * @sealed
+ */
+declare class Message {
+    id: string;
+    timestamp: number;
+    status?: "pending" | "processed" | "failed" | "delivered";
+    checksum?: string;
+    private _body;
+    constructor(msg: MessageBody);
+    constructor(msg: MessageOptions);
+    get body(): MessageBody;
+    set body(value: MessageBody);
+    verifyChecksum: () => void;
+    private validatebodySize;
+    serialize: () => string;
+    static deserialize: (data: string) => Message;
+}
+
+type Address = string;
+interface PacketOptions {
+    id?: string;
+    subject: string;
+    source: Address;
+    target: Address;
+    headers?: {
+        [key: string]: string | number | boolean | undefined;
+    };
+    message?: Message;
+    ttl?: number;
+    timestamp?: number;
+    signature?: string;
+}
+/**
+ * @public
+ * @remarks
+ * This class represents a message object that can be sent over the network
+ * @sealed
+ */
+declare class Packet {
+    id: string;
+    subject: string;
+    source: Address;
+    target: Address;
+    headers?: PacketOptions['headers'];
+    message?: Message;
+    timestamp: number;
+    ttl?: number;
+    signature?: string;
+    constructor({ id, subject, source, target, headers, message, ttl, signature, timestamp }: PacketOptions);
+    serialize(): string;
+    static deserialize(data: string): Packet;
+    isExpired(): boolean;
+}
+
+declare function SerializeMessage(target: any, propertyKey: string, descriptor: PropertyDescriptor): PropertyDescriptor;
+
+declare const decorators: {
+    SerializeMessage: typeof SerializeMessage;
+};
+
+/**
+ * Shared cryptographic types for Connect and Accelerator
+ */
+/**
+ * Supported ECDH curves
+ */
+type ECDHCurve = 'P-256' | 'P-384';
+/**
+ * JSON Web Key format for public keys
+ */
+interface PublicKeyJWK {
+    kty: 'EC';
+    crv: 'P-256' | 'P-384';
+    x: string;
+    y: string;
+    ext?: boolean;
+}
+/**
+ * Keypair with dehydrated public key (JWK) and CryptoKey private key
+ */
+interface Keypair {
+    publicKey: PublicKeyJWK;
+    privateKey: CryptoKey;
+}
+/**
+ * Dehydrated keypair (both keys as strings for transport/storage)
+ */
+interface DehydratedKeypair {
+    publicKey: string;
+    privateKey: string;
+}
+
+/**
+ * Shared identity types for Connect and Accelerator
+ */
+/**
+ * User identity - public key is the primary identifier
+ */
+interface UserIdentity {
+    publicKey: string;
+    accountType: 'self-sovereign' | 'custodial';
+    did?: string;
+    provider?: string;
+    createdAt: number;
+}
+/**
+ * Session
+ */
+interface Session {
+    sessionId: string;
+    publicKey: string;
+    appPublicKey: string;
+    createdAt: number;
+    expiresAt: number;
+    sharedSecret?: string;
+}
+/**
+ * Authentication types
+ */
+type AuthType = 'self-sovereign' | 'custodial';
+/**
+ * OAuth provider types
+ */
+type OAuthProvider = 'google' | 'github' | 'discord' | 'twitter';
+
+/**
+ * Shared permission types for Connect and Accelerator
+ */
+/**
+ * Permission types for resources
+ */
+type Permission = 'read' | 'write' | 'delete' | 'admin' | 'share' | 'invite';
+/**
+ * Role types
+ */
+type Role = 'owner' | 'admin' | 'editor' | 'viewer' | 'member';
+/**
+ * ACL Entry - grants permissions to a user (identified by public key)
+ */
+interface ACLEntry {
+    subject: string;
+    permissions: Permission[];
+    role?: Role;
+    expiresAt?: number;
+    conditions?: {
+        ipAllowlist?: string[];
+        ipBlocklist?: string[];
+        validAfter?: number;
+        validBefore?: number;
+    };
+}
+/**
+ * Access Control List for a resource
+ */
+interface ACL {
+    resource: string;
+    entries: Record<string, ACLEntry>;
+    defaultPermissions?: Permission[];
+    publicPermissions?: Permission[];
+    inheritFromParent?: boolean;
+    createdAt: number;
+    updatedAt: number;
+    createdBy: string;
+}
+/**
+ * Participant in a shared space
+ */
+interface Participant {
+    publicKey: string;
+    role: Role;
+    addedAt: number;
+    addedBy: string;
+    customPermissions?: Permission[];
+}
+/**
+ * Permission check request
+ */
+interface PermissionCheckRequest {
+    publicKey: string;
+    resource: string;
+    requiredPermissions: Permission | Permission[];
+    context?: {
+        timestamp?: number;
+        ipAddress?: string;
+    };
+}
+/**
+ * Permission check result
+ */
+interface PermissionCheckResult {
+    granted: boolean;
+    reason?: string;
+    grantedBy?: string;
+    permissions: Permission[];
+}
+
+/**
+ * Shared messaging types for Connect and Accelerator
+ */
+/**
+ * Message event for pub/sub messaging
+ */
+interface MessageEvent {
+    type: string;
+    topic: string;
+    data: any;
+    senderPublicKey?: string;
+    timestamp: number;
+}
+/**
+ * Message subscription
+ */
+interface Subscription {
+    connectionId: string;
+    publicKey: string;
+    topic: string;
+    filters?: any;
+}
+/**
+ * WebSocket message types
+ */
+type WSMessageType = 'connect' | 'connected' | 'subscribe' | 'subscribed' | 'unsubscribe' | 'publish' | 'event' | 'message' | 'error';
+/**
+ * WebSocket message
+ */
+interface WSMessage {
+    type: WSMessageType;
+    topic?: string;
+    data?: any;
+    publicKey?: string;
+    connectionId?: string;
+    timestamp?: number;
+}
+
+/**
+ * Shared zero-knowledge types and circuit constants.
+ *
+ * Used by both the browser/server builds (where snarkjs handles proof generation
+ * and verification) and the workers build (where verification runs through
+ * `bn128.wasm` via `src/workers/groth16-verifier.ts`). Keeping these here ensures
+ * proof shapes and verification keys stay identical across runtimes.
+ */
+/**
+ * Groth16 proof structure (BN128).
+ *
+ * - `pi_a`: G1 point as `[x, y]` or projective `[x, y, z]`.
+ * - `pi_b`: G2 point as `[[x0, x1], [y0, y1]]` or projective `[..., [z0, z1]]`.
+ * - `pi_c`: G1 point as `[x, y]` or projective `[x, y, z]`.
+ *
+ * Field elements are decimal-string-encoded BigInts (snarkjs convention).
+ */
+interface Groth16Proof {
+    pi_a: string[];
+    pi_b: string[][];
+    pi_c: string[];
+    protocol?: string;
+    curve?: string;
+}
+/**
+ * Groth16 verification key (BN128).
+ *
+ * Field elements are decimal-string-encoded BigInts (snarkjs convention).
+ */
+interface VerificationKey {
+    protocol: string;
+    curve: string;
+    nPublic: number;
+    vk_alpha_1: string[];
+    vk_beta_2: string[][];
+    vk_gamma_2: string[][];
+    vk_delta_2: string[][];
+    vk_alphabeta_12: string[][][];
+    IC: string[][];
+}
+/**
+ * Verification key for the `preimagePoK` circuit (Poseidon-commitment
+ * proof-of-knowledge with three public signals: commitment, nonce, ecdsaPubHash).
+ *
+ * Pinned here so worker-side and SDK-side verification agree on the key being
+ * checked. If the circuit is recompiled, regenerate this constant and
+ * `public/circuits/build/preimagePoK_verification_key.json` together.
+ */
+declare const PREIMAGE_POK_VERIFICATION_KEY: VerificationKey;
+
+/**
+ * WebCrypto subtle-interface resolver.
+ *
+ * Available natively in every runtime this SDK targets (modern browsers,
+ * Node 16+, CF Workers). Centralized here so the runtime check + error
+ * message are consistent across every primitive — and so a future polyfill
+ * shim has one place to plug in.
+ */
+declare function getSubtle(): SubtleCrypto;
+
+/**
+ * Cryptographically secure random bytes.
+ *
+ * Wraps `crypto.getRandomValues` with two small affordances every caller
+ * needs:
+ *   - Allocates over a fresh, non-shared `ArrayBuffer` so the returned
+ *     `Uint8Array` satisfies WebCrypto's `BufferSource` type under strict
+ *     TS lib settings (where `Uint8Array<ArrayBufferLike>` isn't directly
+ *     assignable).
+ *   - Chunks requests larger than 65 KiB, the per-call cap browsers enforce
+ *     on `getRandomValues`.
+ */
+declare function randomBytes(n: number): Uint8Array;
+
+/**
+ * AES-256-GCM encryption / decryption with raw key bytes.
+ *
+ * The two functions here are the single canonical AES-GCM call site in the
+ * SDK. Earlier copies of this logic existed inline in `DoubleRatchet`, in the
+ * storage `ChunkCipher`, and in the passphrase-wrap helpers — they all now
+ * route through here so the algorithm, IV size, and tag handling stay in one
+ * place.
+ *
+ * Conventions:
+ *   - 256-bit keys only. Passing 16- or 24-byte keys throws; callers that
+ *     need AES-128 should add a dedicated primitive.
+ *   - 96-bit IVs. WebCrypto's recommended GCM IV length; trades the 4-byte
+ *     IV economy of 128-bit for compatibility with every spec-compliant
+ *     implementation.
+ *   - The 16-byte GCM authentication tag is appended to the ciphertext by
+ *     WebCrypto's default behavior. Callers don't manage it separately.
+ *
+ * If a future need arises for AAD (associated data), add an optional `aad`
+ * parameter to both functions rather than introducing a parallel primitive.
+ */
+/** Length of the AES key in bytes. */
+declare const AES_GCM_KEY_BYTES = 32;
+/** Length of the AES-GCM IV in bytes (WebCrypto-recommended). */
+declare const AES_GCM_IV_BYTES = 12;
+/** Length of the AES-GCM authentication tag in bytes (appended to ciphertext). */
+declare const AES_GCM_TAG_BYTES = 16;
+/**
+ * Encrypt `plaintext` under a 32-byte AES-256 key with the supplied 12-byte
+ * IV. Returns ciphertext with the 16-byte GCM tag appended (so the output
+ * length is `plaintext.length + 16`).
+ *
+ * The IV must be unique per (key, message). Callers that generate the IV
+ * randomly should grab it via `randomBytes(AES_GCM_IV_BYTES)`; callers
+ * managing a counter pass their own.
+ */
+declare function encryptAesGcm(key: Uint8Array, iv: Uint8Array, plaintext: Uint8Array): Promise<Uint8Array>;
+/**
+ * Inverse of {@link encryptAesGcm}. Throws if the GCM auth tag fails — this
+ * captures "wrong key", "wrong IV", or "ciphertext was tampered with",
+ * indistinguishably. Callers that care about distinguishing those should
+ * keep separate provenance bookkeeping, not invent a parallel MAC.
+ */
+declare function decryptAesGcm(key: Uint8Array, iv: Uint8Array, ciphertext: Uint8Array): Promise<Uint8Array>;
+
+/**
+ * Key-derivation primitives — PBKDF2 (for passphrase → key) and HKDF (for
+ * symmetric key material → expanded key material).
+ *
+ * PBKDF2 is the slow, salted KDF the passphrase-wrap helper uses to harden
+ * user passwords against offline guessing. HKDF is the fast, deterministic
+ * KDF the Double Ratchet uses to derive root + chain + message keys from
+ * shared secrets.
+ *
+ * Both are SHA-256-backed everywhere in this codebase — keep it that way
+ * unless there's a concrete reason to diverge.
+ */
+/**
+ * Iteration count default for PBKDF2 passphrase hardening. Tuned for
+ * 2024–2026 hardware: slow enough to deter offline guessing of weak
+ * passphrases (~100ms on commodity laptops), fast enough that interactive
+ * unlock stays sub-second.
+ */
+declare const PBKDF2_DEFAULT_ITERATIONS = 200000;
+/**
+ * Derive a 256-bit AES-GCM key from `passphrase + salt` via PBKDF2-SHA256.
+ *
+ * Returned as raw bytes (not a `CryptoKey`) so callers can hand it straight
+ * to {@link encryptAesGcm} — that's the convention everywhere else in the
+ * primitive layer. If a future caller needs the non-extractable
+ * `CryptoKey` form, add a parallel `deriveCryptoKeyFromPassphrase` variant
+ * rather than overloading this one.
+ */
+declare function deriveAesKeyFromPassphrase(passphrase: string, salt: Uint8Array, iterations?: number): Promise<Uint8Array>;
+/**
+ * HKDF-Expand with SHA-256, returning `lengthBytes` raw bytes of key material.
+ *
+ * `info` is the per-purpose label (e.g. `"DoubleRatchetMsg"`). Optional
+ * `salt` defaults to an empty buffer, matching the way the Double Ratchet
+ * code has always used it.
+ *
+ * Note: this is intentionally a one-shot Extract-then-Expand call rather than
+ * exposing Extract and Expand separately — every call site in this codebase
+ * wants the same shape, and a richer API can be added later if needed.
+ */
+declare function deriveBitsHkdf(inputKeyMaterial: Uint8Array, info: string, lengthBytes: number, salt?: Uint8Array): Promise<Uint8Array>;
+
+interface KeyPair {
+    privateKey: CryptoKey | null;
+    publicKey: CryptoKey;
+}
+interface AuthKeyPair {
+    privateKey: CryptoKey | null;
+    publicKey: CryptoKey;
+}
+interface DehydratedKeys {
+    ecdhPub: string;
+    ecdhPriv: string;
+    ecdsaPub: string;
+    ecdsaPriv: string;
+}
+declare class KeyStore {
+    private static instance;
+    private _keys;
+    private _authKeys;
+    private constructor();
+    static getInstance(): KeyStore;
+    get keys(): Map<string, KeyPair>;
+    get authKeys(): Map<string, AuthKeyPair>;
+    generateOwnKeyPair(id: string): Promise<KeyPair>;
+    storeRemotePublicKeys(id: string, ecdhPublicKey: CryptoKey, ecdsaPublicKey: CryptoKey): Promise<void>;
+    hydrateKeyPair(id: string, dehydrated: DehydratedKeys): Promise<void>;
+    getKeyPair(id: string): KeyPair | null;
+    getAuthKeyPair(id: string): AuthKeyPair | null;
+    dehydrateKeyPair(id: string): Promise<DehydratedKeys>;
+    getRawEcdsaPublicKey(id: string): Promise<Uint8Array | null>;
+    packDehydratedKeys(id: string): Promise<string>;
+    hydrateFromPacked(id: string, masterKey: string): Promise<void>;
+}
+
+interface CipherMessageHeader {
+  dhPub: string;
+  prevChainLength: number;
+  messageNumber: number;
+  sessionId: string;
+  sessionType: 'global' | 'specific';
+  senderId: string;
+  recipientId: string;
+  timestamp: number;
+  signature: string;
+}
+
+interface CipherMessage {
+  header: CipherMessageHeader;
+  ciphertext: string; // Hex-encoded
+  nonce: string; // Hex-encoded
+}
+
+// interface RatchetState {
+//   clientDhPriv: Uint8Array;
+//   clientDhPub: Uint8Array;
+//   serverDhPriv: Uint8Array;
+//   serverDhPub: Uint8Array;
+//   rootKey: Uint8Array | null;
+//   sendChainKey: Uint8Array | null;
+//   recvChainKey: Uint8Array | null;
+//   sendCount: number;
+//   recvCount: number;
+//   prevChainLength: number;
+//   skippedKeys: Map<number, Uint8Array>;
+// }
+
+// interface RatchetState {
+//   clientDhPriv: CryptoKey | null; // ECDH private key
+//   clientDhPub: CryptoKey; //
+//   serverDhPriv: CryptoKey | null; // ECDH private key
+//   serverDhPub: CryptoKey; // ECDH public key
+//   rootKey: CryptoKey | null; // AES-GCM key
+//   sendChainKey: CryptoKey | null; // AES-GCM key for sending
+//   recvChainKey: CryptoKey | null; // AES-GCM key for receiving
+//   sendCount: number; // Number of messages sent
+//   recvCount: number; // Number of messages received
+//   prevChainLength: number; // Length of the previous chain
+//   skippedKeys: Map<number, CryptoKey>; // Skipped keys for messages
+// }
+
+interface RatchetState {
+    clientDhPriv: CryptoKey  | null;
+    clientDhPub: CryptoKey ;
+    serverDhPriv: CryptoKey  | null;
+    serverDhPub: CryptoKey ;
+    // Symmetric key material (root key + chain keys + skipped message keys).
+    // Stored as Uint8Array rather than Node's Buffer so this type works in the
+    // browser/Workers builds.
+    rootKey: Uint8Array | null;
+    sendChainKey: Uint8Array | null;
+    recvChainKey: Uint8Array | null;
+    sendCount: number;
+    recvCount: number;
+    prevChainLength: number;
+    currentSkippedKeys: Map<number, Uint8Array>;
+    oldSkippedMessageKeys: Map<string, { skips: Map<number, Uint8Array>; created: number }>;
+}
+
+declare class DoubleRatchet {
+    private state;
+    private sessionType;
+    private maxSkip;
+    private overlapPeriod;
+    private windowSize;
+    constructor(senderId: string, recipientId: string, sessionType: 'global' | 'specific', isClient?: boolean);
+    private hkdf;
+    initializeSession(isClient?: boolean): Promise<void>;
+    private dhRatchet;
+    private symmetricRatchet;
+    encrypt(plaintext: string, newDhKey: boolean | undefined, senderId: string, recipientId: string, sessionId: string, sessionType: 'global' | 'specific'): Promise<CipherMessage>;
+    private cleanOldSkippedKeys;
+    decrypt(message: CipherMessage, isClient?: boolean): Promise<string>;
+    getState(): RatchetState;
+    setState(state: RatchetState): void;
+}
+
+type SnarkProof = Groth16Proof;
+
+interface ZkCompiled {
+    verificationKey: VerificationKey;
+}
+declare class AuthPublicInput {
+    commitment: string;
+    nonce: string;
+    ecdsaPubHash: string;
+    constructor(commitment: string, nonce: string, ecdsaPubHash: string);
+    toPublicSignals(): string[];
+}
+declare class Field {
+    private value;
+    static readonly FIELD_SIZE: bigint;
+    constructor(value: bigint | string | number);
+    toBigInt(): bigint;
+    toString(): string;
+    toHex(): string;
+    equals(other: Field): boolean;
+    static fromHex(hex: string): Field;
+}
+declare class Poseidon {
+    static hash(inputs: Field[]): Promise<Field>;
+}
+declare function encodeToHex(field: Field): string;
+declare function decodeFromHex(hexStr: string): Field;
+interface CircuitBufferConfig {
+    wasm: Uint8Array;
+    zkey: Uint8Array;
+    verificationKey: VerificationKey;
+}
+declare class HashKnowledge {
+    private static wasmBuffer?;
+    private static zkeyBuffer?;
+    private static verificationKey?;
+    static setCircuitBuffers(wasm: Uint8Array, zkey: Uint8Array, verificationKey: VerificationKey): void;
+    static compile(): Promise<ZkCompiled>;
+    static prove(secret: Field): Promise<{
+        proof: SnarkProof;
+        publicSignals: string[];
+    }>;
+    static verify(proof: SnarkProof, publicSignals?: string[]): Promise<boolean>;
+}
+declare class PreimagePoK {
+    private static wasmBuffer?;
+    private static zkeyBuffer?;
+    private static verificationKey?;
+    static setCircuitBuffers(wasm: Uint8Array, zkey: Uint8Array, verificationKey: VerificationKey): void;
+    static compile(): Promise<ZkCompiled>;
+    static prove(publicInput: AuthPublicInput, secret: Field, salt: Field, ecdsaPub: Field): Promise<{
+        proof: SnarkProof;
+        publicSignals: string[];
+    }>;
+    static verify(proof: SnarkProof, publicSignals?: string[]): Promise<boolean>;
+}
+declare function verifyHashKnowledge(proof: SnarkProof, expectedOutput?: Field, publicSignals?: string[]): Promise<boolean>;
+declare function verifyPreimagePoK(proof: SnarkProof, publicSignals?: string[]): Promise<boolean>;
+declare function verify(programType: 'HashKnowledge' | 'PreimagePoK', proof: SnarkProof, options?: {
+    expectedOutput?: Field;
+    publicSignals?: string[];
+}): Promise<boolean>;
+declare function quickVerify(program: typeof HashKnowledge | typeof PreimagePoK, proof: SnarkProof, publicSignals?: string[]): Promise<boolean>;
+declare function initializeCircuits(config: {
+    hashKnowledge?: CircuitBufferConfig;
+    preimagePoK?: CircuitBufferConfig;
+}): void;
+declare function compilePrograms(): Promise<{
+    hashKnowledge: ZkCompiled;
+    preimagePoK: ZkCompiled;
+}>;
+
+interface AuthToken {
+    peerId: string;
+    timestamp: number;
+    signature: string;
+}
+declare class Authenticator {
+    private trustedKeys;
+    private zkVerificationKey;
+    initializeZK(): Promise<void>;
+    getZKVerificationKey(): VerificationKey | null;
+    addTrustedServer(serverId: string, publicKey: CryptoKey): void;
+    generateAuthToken(peerId: string, privateKey: CryptoKey): Promise<AuthToken>;
+    verifyAuthToken(token: AuthToken, clientPublicKey: CryptoKey): Promise<boolean>;
+    verifyZKProof(proof: any, publicInput: AuthPublicInput, storedCommitment: Field, ecdsaPub: CryptoKey): Promise<boolean>;
+}
+
+declare class DoubleRatchetManager {
+    private sessions;
+    private sessionStates;
+    private keyStore;
+    private _authenticator;
+    private registeredUsers;
+    private id;
+    constructor(id: string);
+    get authenticator(): Authenticator;
+    addTrustedServer(serverId: string, publicKey: CryptoKey): Promise<void>;
+    registerZK(clientId: string, secret: Field, salt: Field, ecdsaPub: CryptoKey): Promise<void>;
+    performHandshake(senderId: string, recipientId: string, zkProof: any, publicInput: AuthPublicInput, clientPublicKey: CryptoKey, // ECDH pub for session
+    clientAuthPublicKey: CryptoKey, // ECDSA pub for auth
+    authToken: AuthToken): Promise<void>;
+    initializeSession(senderId: string, recipientId: string, isClient?: boolean, sessionType?: 'global' | 'specific', sessionId?: string, zkProof?: any, publicInput?: AuthPublicInput, clientPublicKey?: CryptoKey, clientAuthPublicKey?: CryptoKey, clientEcdhPrivateKey?: CryptoKey, clientAuthPrivateKey?: CryptoKey): Promise<string>;
+    encrypt(senderId: string, recipientId: string, sessionId: string, plaintext: string, newDhKey?: boolean, sessionType?: 'global' | 'specific'): Promise<CipherMessage>;
+    decrypt(message: CipherMessage, isClient?: boolean): Promise<string>;
+    getSessionSharedSecret(sessionId: string): Promise<Uint8Array | null>;
+    private saveState;
+    private loadState;
+}
+
+/**
+ * Per-chunk AES-256-GCM encryption with random keys and IVs.
+ *
+ * Each chunk of a stored file gets its own freshly generated 256-bit AES key
+ * and 96-bit IV. The (key, IV) pair lives in the file manifest, which the
+ * application is responsible for storing under whatever access-control regime
+ * it uses (in this codebase: the `SharedSpaceClient` writes manifests into
+ * ZK-gated multi-user spaces; the shard store itself is open).
+ *
+ * Per-chunk keys (rather than a per-file DEK) lets future versions revoke or
+ * re-share individual chunks without re-encrypting the whole file. The
+ * additional manifest size is dominated by the shard hash list anyway.
+ *
+ * The cipher itself delegates to the canonical `encryptAesGcm` / `decryptAesGcm`
+ * primitives — this class only wraps them with key-material generation and
+ * the JSON-friendly base64 serialization the manifest needs.
+ */
+/**
+ * Per-chunk key material, base64-encoded for JSON-friendly storage in the
+ * manifest. The IV is unique per chunk; the key is unique per chunk too in
+ * this codebase, though that's a stricter property than AES-GCM strictly
+ * requires (which is "unique IV per key").
+ */
+interface ChunkKeyMaterial {
+    /** Base64-encoded 32-byte AES-256 key. */
+    key: string;
+    /** Base64-encoded 12-byte AES-GCM IV. */
+    iv: string;
+}
+declare class ChunkCipher {
+    /**
+     * Generate a fresh random (key, iv) pair encoded for the manifest.
+     * Callers should generate one of these per chunk before calling
+     * {@link encryptChunk}.
+     */
+    generateKeyMaterial(): ChunkKeyMaterial;
+    /**
+     * Encrypt `plaintext` under the supplied key + IV. Returns the AES-GCM
+     * ciphertext with the 16-byte auth tag appended (WebCrypto's default
+     * GCM behavior).
+     */
+    encryptChunk(plaintext: Uint8Array, material: ChunkKeyMaterial): Promise<Uint8Array>;
+    /**
+     * Inverse of {@link encryptChunk}. Throws if the auth tag fails — that
+     * means the ciphertext was tampered with, the key/iv was wrong, or the
+     * shards were reassembled incorrectly.
+     */
+    decryptChunk(ciphertext: Uint8Array, material: ChunkKeyMaterial): Promise<Uint8Array>;
+}
+
+/**
+ * Passphrase-based wrap / unwrap helpers using WebCrypto.
+ *
+ * Encrypt a payload with a user-supplied passphrase before persisting it
+ * somewhere the server can see (e.g. the manifest blob in a ZK-gated
+ * SharedSpace, or chat-key material in a PersonalSpace). The server never
+ * sees the passphrase or the plaintext — both wrap and unwrap run entirely
+ * client-side.
+ *
+ * Algorithm (the only one this codebase has ever shipped):
+ *   - PBKDF2-SHA256 with 200_000 iterations derives a 256-bit AES key from
+ *     `passphrase || salt`.
+ *   - AES-256-GCM encrypts the plaintext with a fresh random 12-byte IV.
+ *   - The auth tag is appended to the ciphertext by WebCrypto's default
+ *     GCM behaviour, so {@link WrappedPayload.ciphertext} carries it implicitly.
+ *
+ * The returned {@link WrappedPayload} is JSON-friendly (all base64 fields), so
+ * it can be `JSON.stringify`-ed straight into a KV layer.
+ */
+/**
+ * The persisted, JSON-friendly representation of a passphrase-wrapped blob.
+ *
+ * The `alg` field is a self-describing marker — if we ever rotate KDF/cipher,
+ * unwrap can switch on this value to keep older payloads readable.
+ */
+interface WrappedPayload {
+    /** Random per-wrap salt for PBKDF2, base64. */
+    salt: string;
+    /** AES-GCM IV, base64. */
+    iv: string;
+    /** AES-GCM ciphertext (includes 16-byte GCM auth tag), base64. */
+    ciphertext: string;
+    /** Algorithm marker so future readers know what they're looking at. */
+    alg: "PBKDF2-SHA256/AES-256-GCM";
+    /** PBKDF2 iteration count used. */
+    iter: number;
+}
+/**
+ * Encrypt `plaintext` under a key derived from `passphrase`. The returned
+ * payload bundles the salt, IV, and ciphertext so unwrap only needs the
+ * passphrase to reverse the operation.
+ */
+declare function wrapWithPassphrase(passphrase: string, plaintext: Uint8Array): Promise<WrappedPayload>;
+/**
+ * Decrypt a {@link WrappedPayload} produced by {@link wrapWithPassphrase}.
+ * Throws if the passphrase is wrong, the payload is tampered with, or the
+ * algorithm marker is unrecognised.
+ */
+declare function unwrapWithPassphrase(passphrase: string, wrapped: WrappedPayload): Promise<Uint8Array>;
+
+declare enum EventCoreEvents {
+    CONNECTED = "connected",
+    DISCONNECTED = "disconnected",
+    RECONNECTING = "reconnecting",
+    ERROR = "error",
+    DATA_RECEIVED = "data_received",
+    DATA_SENT = "data_sent",
+    MESSAGE = "message",
+    GET_HISTORY = "get_history",
+    RECEIVED_HISTORY = "received_history"
+}
+/**
+ * @public
+ * EventCore is a static event emitter with singleton functionality for global event handling.
+ */
+declare class EventCore {
+    private static eventTarget;
+    private static events;
+    /**
+     * @remarks Listen to an event.
+     * @example EventCore.on('event', (e) =\> appLogger.debug(e));
+     */
+    static on(event: EventCoreEvents, handler: EventListener | CallableFunction): void;
+    /**
+     * @remarks Stop listening to an event.
+     * @example EventCore.off('event', handler);
+     */
+    static off(event: EventCoreEvents, handler: EventListener | CallableFunction): void;
+    /**
+     * @remarks Emit an event.
+     * @example EventCore.emit('event', data);
+     */
+    static emit(event: EventCoreEvents, data: any): void;
+}
+
+/**
+ * An end-to-end-encrypted communication session for one local identity
+ * (`myId`) talking to an arbitrary set of peers. Wraps `KeyStore` +
+ * per-pair `DoubleRatchet` instances and owns the protocol bookkeeping
+ * (handshake reciprocation, dedup, role assignment, broadcast fan-out,
+ * recipient filtering) so application code doesn't have to.
+ *
+ * Transport-agnostic by design: the Session never touches a WebSocket
+ * (or HTTP, or anything else). Application code:
+ *   - calls `session.encrypt(text)` and gets back an array of frames it
+ *     ships over whatever transport it has;
+ *   - calls `session.receive(frame)` with each inbound frame and acts on
+ *     the typed result (plaintext, handshake-done, ignored).
+ *
+ * Frames are plain JSON objects with the same shape the existing chat
+ * protocol uses (`{ keyExchange: {...} }` and `{ cipherMessage: {...} }`),
+ * so this can drop into a chat app without changing the wire format.
+ */
+
+interface SessionOptions {
+    /** This client's identifier (e.g. username / DID / public-key string). */
+    myId: string;
+}
+/** A handshake frame the application ships to peers (or receives from them). */
+interface KeyExchangeFrame {
+    type: "handshake" | "update";
+    userId: string;
+    /** Base64-encoded JWK of the sender's ECDH public key. */
+    ecdhPublicKey: string;
+    /** Base64-encoded JWK of the sender's ECDSA public key. */
+    ecdsaPublicKey: string;
+}
+/** A ciphertext frame, addressed to exactly one peer. */
+interface CipherFrame {
+    cipherMessage: CipherMessage;
+}
+/** Anything inbound the application might hand to `session.receive()`. */
+type IncomingFrame = {
+    keyExchange: KeyExchangeFrame;
+} | {
+    cipherMessage: CipherMessage;
+} | Record<string, unknown>;
+/** Outcome of feeding one frame through `session.receive()`. */
+type ReceiveResult = {
+    kind: "plaintext";
+    /** The sender's id (from the cipherMessage header). */
+    from: string;
+    /** Decrypted message body. */
+    text: string;
+    /** The original cipherMessage, for callers that want it. */
+    cipherMessage: CipherMessage;
+} | {
+    kind: "handshake";
+    /** The peer whose handshake was just processed. */
+    peerId: string;
+    /**
+     * If non-null, the application MUST send this frame back to the peer
+     * (e.g. broadcast on the room WebSocket). It's our reciprocation —
+     * giving the peer our public keys so they can verify our messages.
+     *
+     * The Session dedups internally: we only emit this on the first
+     * handshake we process for a given peer in this Session's lifetime.
+     */
+    outbound: {
+        keyExchange: KeyExchangeFrame;
+    } | null;
+} | {
+    kind: "ignored";
+    /** Why we ignored the frame (debugging aid; not for branching on). */
+    reason: string;
+};
+declare class EncryptedSession {
+    private readonly myId;
+    private readonly keyStore;
+    /** One DoubleRatchet per peer pair. */
+    private readonly ratchets;
+    /** Peers we've already sent our keyExchange to in this Session. */
+    private readonly sentHandshakeTo;
+    /** Resolved when own keys are generated and ready to use. */
+    private readonly _ready;
+    private _resolveReady;
+    private _initialized;
+    constructor(opts: SessionOptions);
+    /** A promise that resolves once `initialize()` has completed. */
+    get ready(): Promise<void>;
+    /** Our local identifier. */
+    get id(): string;
+    /**
+     * Generate this client's ECDH + ECDSA keypair (idempotent — safe to call
+     * multiple times across reconnects; only the first call generates).
+     */
+    initialize(): Promise<void>;
+    /**
+     * Build the keyExchange frame this client should send to peers when it
+     * comes online. Application is responsible for actually transmitting it
+     * (e.g. ws.send(JSON.stringify(frame))).
+     */
+    getOwnKeyExchange(): Promise<{
+        keyExchange: KeyExchangeFrame;
+    }>;
+    /**
+     * Encrypt a plaintext to every peer we currently have a ratchet for, and
+     * return one cipherMessage frame per recipient. The application sends
+     * each frame over its transport.
+     *
+     * If there are no peers yet (or all peers are still mid-handshake), the
+     * returned array may be empty — the caller should typically render the
+     * outgoing message locally in that case (since there's no one to send
+     * it to yet).
+     */
+    encrypt(plaintext: string): Promise<CipherFrame[]>;
+    /**
+     * Hand an inbound frame to the session. Returns a typed result the
+     * application acts on.
+     *
+     *   - `kind: 'plaintext'`         — decrypted; render `result.text`
+     *   - `kind: 'handshake'`         — a peer's keys are now stored, and if
+     *                                   `result.outbound` is set, send it
+     *   - `kind: 'ignored'`           — not for us, malformed, duplicate, etc.
+     *
+     * Calling code should always handle `'ignored'` (no UI side effect).
+     */
+    receive(frame: IncomingFrame): Promise<ReceiveResult>;
+    /** List of peer ids we have an established ratchet for. */
+    peers(): string[];
+    /** Has the handshake completed for this peer? */
+    hasRatchetFor(peerId: string): boolean;
+    /**
+     * Tear down a peer's ratchet (e.g. when they leave the room). The peer's
+     * stored keys remain in `KeyStore` so a fresh handshake can be set up
+     * later without re-fetching them, but the ratchet state is dropped.
+     */
+    forgetPeer(peerId: string): void;
+    /** Deterministic per-pair session id — same string on both sides. */
+    private _sessionIdFor;
+}
+
+/**
+ * Pure WebSocket transport — owns the socket lifecycle and nothing else.
+ *
+ * Hands raw frame strings up (via the `MESSAGE` event) and accepts raw frame
+ * strings down (via `send`). Anything frame-shape, encryption, or serialization
+ * related belongs in the layer above (e.g. `Network` for client↔server
+ * encrypted pipes, `BroadcastChannel` for multi-peer E2E rooms).
+ *
+ * Responsibilities:
+ *   - Open / close the WebSocket
+ *   - Auto-reconnect with linear backoff after an unexpected close
+ *   - Buffer outbound frames while disconnected (capped queue)
+ *   - Emit lifecycle events (CONNECTED / DISCONNECTED / RECONNECTING / ERROR)
+ *     plus raw inbound MESSAGE events
+ */
+
+interface WSTransportOptions {
+    /** WebSocket URL, e.g. `ws://localhost:8787/foo`. */
+    url: string;
+    /** Reconnect automatically after unexpected disconnect (default `true`). */
+    autoReconnect?: boolean;
+    /** Delay between reconnect attempts in ms (default `3000`). */
+    reconnectDelay?: number;
+    /** Cap on reconnect attempts (default `5`; `0` means unlimited). */
+    maxReconnectAttempts?: number;
+    /**
+     * Max outbound frames buffered while disconnected. Sending past this caps
+     * throws synchronously. Default `100`.
+     */
+    maxQueueSize?: number;
+}
+declare class WSTransport extends EventCore {
+    emit: typeof EventCore.emit;
+    on: typeof EventCore.on;
+    off: typeof EventCore.off;
+    private url;
+    private socket;
+    private _isConnected;
+    private _isConnecting;
+    private autoReconnect;
+    private reconnectDelay;
+    private maxReconnectAttempts;
+    private reconnectAttempts;
+    private reconnectTimeout;
+    private outboundQueue;
+    private maxQueueSize;
+    constructor(opts: WSTransportOptions);
+    /** Open the socket. Resolves when CONNECTED fires. Rejects on first error. */
+    connect(): Promise<void>;
+    /** Close the socket and stop reconnecting. */
+    disconnect(): void;
+    /**
+     * Send a raw frame. If currently disconnected, the frame is queued and sent
+     * after the next successful reconnect (up to `maxQueueSize`).
+     */
+    send(frame: string): void;
+    isConnected(): boolean;
+    isConnecting(): boolean;
+    queuedFrames(): number;
+    reconnectAttemptCount(): number;
+    private scheduleReconnect;
+    private flushQueue;
+}
+
+/**
+ * BroadcastChannel — a turnkey end-to-end encrypted channel for multi-peer
+ * "room"-style apps (e.g. a chat). Wires together:
+ *
+ *   - `WSTransport` for socket lifecycle, reconnect, and offline frame queue
+ *   - `EncryptedSession` for per-peer Double Ratchet state, handshake
+ *     reciprocation, fan-out encryption, and recipient filtering
+ *
+ * The host app only deals with high-level events and method calls; it never
+ * touches `new WebSocket(...)` or builds cipherMessage frames by hand.
+ *
+ * Wire protocol (kept compatible with the existing chat protocol so this
+ * drops into the deployed Accelerator without server changes):
+ *
+ *   outbound: `{ keyExchange: {...} }`      — produced by us on `announce()`
+ *             `{ cipherMessage: {...} }`    — produced by `send(text)`,
+ *                                              one frame per peer
+ *             arbitrary JSON                — sent via `sendRaw(obj)`
+ *
+ *   inbound:  `{ keyExchange: {...} }`      — routed into EncryptedSession;
+ *                                              emits `peer_handshake`
+ *             `{ cipherMessage: {...} }`    — decrypted; emits `message`
+ *             anything else                 — passes through as `raw_frame`
+ *                                              (the app decides what to do)
+ *
+ * **Event scoping.** Unlike `Network`, BroadcastChannel uses a per-instance
+ * `EventTarget`, so two channels (e.g. two rooms in the same app) don't
+ * cross-contaminate each other's events.
+ *
+ * Note: this class shadows the `BroadcastChannel` Web API global (cross-tab
+ * messaging) only when imported by name. They're unrelated.
+ */
+
+/**
+ * Event names BroadcastChannel emits. Lifecycle events reuse the
+ * `EventCoreEvents` string values (`connected`, `disconnected`, etc.) so
+ * apps can use shared constants if they want. Channel-specific events are
+ * prefixed `channel:` to avoid colliding with other event systems in the
+ * same app.
+ */
+declare const BroadcastChannelEvents: {
+    readonly CONNECTED: EventCoreEvents.CONNECTED;
+    readonly DISCONNECTED: EventCoreEvents.DISCONNECTED;
+    readonly RECONNECTING: EventCoreEvents.RECONNECTING;
+    readonly ERROR: EventCoreEvents.ERROR;
+    /** A peer's ratchet is now ready. `detail.peerId` is the peer's id. */
+    readonly PEER_HANDSHAKE: "channel:peer_handshake";
+    /** Decrypted message. `detail` is `{ from, text, cipherMessage }`. */
+    readonly MESSAGE: "channel:message";
+    /** Inbound frame BroadcastChannel didn't recognize. App handles it. */
+    readonly RAW_FRAME: "channel:raw_frame";
+};
+type BroadcastChannelEvent = (typeof BroadcastChannelEvents)[keyof typeof BroadcastChannelEvents];
+interface BroadcastChannelOptions extends WSTransportOptions {
+    /** This client's identifier (username, DID, public-key string, etc.). */
+    myId: string;
+    /**
+     * If true (default false), automatically send our keyExchange as soon as
+     * the socket is connected. For chat-style apps that send a `{name}` frame
+     * first, leave this false and call `announce()` after that handshake.
+     */
+    autoAnnounce?: boolean;
+}
+declare class BroadcastChannel {
+    readonly transport: WSTransport;
+    readonly session: EncryptedSession;
+    readonly myId: string;
+    private autoAnnounce;
+    private announced;
+    /** Per-instance EventTarget — events do NOT leak across BroadcastChannels. */
+    private events;
+    constructor(opts: BroadcastChannelOptions);
+    /** Subscribe to a channel event. Handler receives a CustomEvent. */
+    on(event: BroadcastChannelEvent | string, handler: (e: CustomEvent) => void): void;
+    /** Unsubscribe. */
+    off(event: BroadcastChannelEvent | string, handler: (e: CustomEvent) => void): void;
+    private emit;
+    /** Generate our keys (idempotent) and open the WebSocket. */
+    connect(): Promise<void>;
+    /** Close the WebSocket and stop reconnecting. */
+    disconnect(): void;
+    /**
+     * Send our `keyExchange` frame to the room. Idempotent — only sends on the
+     * first call. Call this once your higher-level handshake (e.g. sending a
+     * `{name}` identification frame) has completed.
+     */
+    announce(): Promise<void>;
+    /**
+     * Encrypt `plaintext` to every peer we have a ratchet with, and send each
+     * cipherMessage as its own WS frame. Returns the number of peers we sent to
+     * (0 if no peers are handshaken yet — in which case the caller should
+     * typically render the message locally for the sender and try again later).
+     */
+    send(plaintext: string): Promise<number>;
+    /**
+     * Send an arbitrary JSON-serializable frame as-is. The app uses this for
+     * any frame that isn't channel-managed (e.g. a chat's `{name}`, `{file}`,
+     * or unencrypted `{message}`).
+     */
+    sendRaw(frame: unknown): void;
+    /** List of peer ids we have an established ratchet for. */
+    peers(): string[];
+    /** Drop a peer's ratchet (e.g. when they leave the room). */
+    forgetPeer(peerId: string): void;
+    isConnected(): boolean;
+    private handleInboundFrame;
+}
+
+/**
+ * Cloudflare-Workers-compatible Groth16 ZK proof verifier.
+ *
+ * Drives the BN128 WASM module's exported pairing functions directly. Does NOT
+ * use snarkjs/ffjavascript — those depend on runtime features (most notably
+ * `URL.createObjectURL`) that CF Workers don't expose. See ROADMAP / CLAUDE.md.
+ *
+ * Two ways to initialize:
+ *   1. `await initBn128Wasm()` — uses the bundled bn128.wasm (base64-inlined at
+ *      build time via `@rollup/plugin-wasm`). Works in any modern JS runtime
+ *      that allows runtime `WebAssembly.compile()` — Node, browsers, most
+ *      Workers configurations.
+ *   2. `await initBn128Wasm(myWasmModule)` — accepts a pre-compiled
+ *      `WebAssembly.Module`. Lets a CF-Workers consumer keep the native pattern
+ *      of importing `.wasm` so wrangler precompiles it at deploy time and the
+ *      worker never pays for runtime compilation.
+ */
+
+interface Bn128WasmInstance {
+    instance: WebAssembly.Instance;
+    memory: WebAssembly.Memory;
+    initialPFree: number;
+}
+/**
+ * Initialize the BN128 WASM module.
+ *
+ * @param wasmModule Optional pre-compiled `WebAssembly.Module`. If omitted, the
+ *   bundled bn128.wasm (base64-inlined by `@rollup/plugin-wasm` at build time)
+ *   is used. Passing your own module is the recommended path inside CF Workers,
+ *   where wrangler can precompile a `.wasm` import at deploy time and avoid the
+ *   runtime compile cost.
+ */
+declare function initBn128Wasm(wasmModule?: WebAssembly.Module): Promise<Bn128WasmInstance>;
+/**
+ * Verify a Groth16 proof.
+ *
+ * Returns `false` (rather than throwing) for any structural problem — malformed
+ * proof, out-of-range field elements, off-curve points, or a failed pairing.
+ * Throws only for runtime/WASM faults.
+ */
+declare function verifyGroth16(wasmInstance: WebAssembly.Instance, memory: WebAssembly.Memory, initialPFree: number, verificationKey: VerificationKey, proof: Groth16Proof, publicSignals: string[]): Promise<boolean>;
+
+/**
+ * `PersonalSpaceClient` — the client-side counterpart to the accelerator's
+ * `PersonalSpaceDO`. Wraps the `/api/personal/:commitment/*` HTTP protocol so
+ * callers can `put` / `get` / `delete` / `list` per-user KV blobs without
+ * thinking about challenges, nonces, or Groth16 proof generation.
+ *
+ * Every gated operation:
+ *   1. Requests a one-shot challenge from the DO (`POST /challenge`).
+ *   2. Converts the returned hex nonce into a BN254 field element.
+ *   3. Generates a fresh Groth16 proof for the `preimagePoK` circuit using
+ *      snarkjs, with the user's secret/salt/ecdsaPub as private inputs and
+ *      `{commitment, nonce, ecdsaPubHash}` as public signals.
+ *   4. POSTs the proof + publicSignals + (optional) value to the gated endpoint.
+ *
+ * snarkjs is loaded lazily (dynamic `import`) the first time a proof is
+ * generated — it's an optional peer dependency that only the ZK-proof path
+ * needs, so importing this module (or constructing a `Client`) never requires
+ * it. Consumers using the proof path install `snarkjs`, or provide it via an
+ * import map in the browser (see the README).
+ *
+ * Encryption of the stored values is the caller's responsibility — the DO
+ * sees only opaque JSON. The companion `wrap.ts` helpers in this folder are
+ * a convenient way to passphrase-encrypt a payload before putting it.
+ */
+/**
+ * Constructor options for {@link PersonalSpaceClient}.
+ *
+ * All of `secret`, `salt`, `ecdsaPub`, and `ecdsaPubHash` are decimal-encoded
+ * BigInt strings (snarkjs convention). `commitment` is likewise decimal — it's
+ * the Poseidon hash of `(secret, salt, ecdsaPubHash)`.
+ */
+interface PersonalSpaceClientOptions {
+    /** Base URL of the accelerator, e.g. `http://localhost:8787`. */
+    baseUrl: string;
+    /** The user's Poseidon commitment as a decimal string (~78 digits). */
+    commitment: string;
+    /** ZK identity material — private inputs to the proof. Decimal BigInt string. */
+    secret: string;
+    /** ZK identity salt. Decimal BigInt string. */
+    salt: string;
+    /** Raw ECDSA public-key field representation. Decimal BigInt string. */
+    ecdsaPub: string;
+    /** Poseidon hash of `ecdsaPub`, used as a public signal. Decimal BigInt string. */
+    ecdsaPubHash: string;
+    /** Where the runtime can fetch the compiled circuit assets. */
+    circuits: {
+        /** URL of the `preimagePoK.wasm` witness generator. */
+        wasmUrl: string;
+        /** URL of the `preimagePoK_0001.zkey` proving key. */
+        zkeyUrl: string;
+    };
+}
+declare class PersonalSpaceClient {
+    private readonly baseUrl;
+    private readonly commitment;
+    private readonly secret;
+    private readonly salt;
+    private readonly ecdsaPub;
+    private readonly ecdsaPubHash;
+    private readonly wasmUrl;
+    private readonly zkeyUrl;
+    constructor(opts: PersonalSpaceClientOptions);
+    /** Store `value` under `key`, replacing any prior value. */
+    put(key: string, value: unknown): Promise<void>;
+    /** Fetch the value stored under `key`. Returns `null` if absent. */
+    get<T = unknown>(key: string): Promise<T | null>;
+    /** Remove `key` from the user's space. Returns whether the key existed. */
+    delete(key: string): Promise<boolean>;
+    /** List every key currently stored in the user's space. */
+    list(): Promise<string[]>;
+    /**
+     * Run the full pre-flight: ask the DO for a challenge, reduce the nonce to
+     * a field element, and generate a fresh Groth16 proof. Returns everything
+     * the gated endpoints need in their body.
+     */
+    private proveFreshChallenge;
+    /** Hit `POST /challenge` and return the issued nonce + ID. */
+    private requestChallenge;
+    /**
+     * Thin wrapper over `globalThis.fetch` so all methods share a single set of
+     * headers and body-encoding behaviour. `globalThis.fetch` is available in
+     * modern browsers, Node 18+, Workers, and Bun.
+     */
+    private fetch;
+}
+
+/**
+ * Wire types for the storage layer.
+ *
+ * The `FileManifest` is the single piece of metadata the system needs to
+ * reassemble a file: per-chunk encryption material, RS parameters, and the
+ * SHA-256 content hashes of every shard that belongs to the chunk. With the
+ * manifest in hand, a reader can pull each shard from the open content-
+ * addressed shard store, decode, decrypt, and concatenate to recover the
+ * original bytes.
+ *
+ * The manifest itself lives inside a `SharedSpaceDO` (Phase B) which gates
+ * access by ZK proof + ACL. Shards are stored in the open content-addressed
+ * `ShardStoreDO` — anyone can put/get any shard, but without the manifest
+ * (which has the keys) the ciphertext is just noise.
+ */
+
+/**
+ * One chunk's metadata. A file is the concatenation of `chunks` in order.
+ *
+ * - `originalSize` is the chunk's plaintext length, before AES-GCM expanded
+ *   it by 16 bytes for the auth tag and before RS padded it for shard
+ *   alignment.
+ * - `ciphertextSize` is the AES-GCM output length (plaintext + 16). This is
+ *   what the RS decoder trims back to.
+ * - `shardHashes` lists every shard's SHA-256 in encoding order — the first
+ *   `dataShards` are data shards, the trailing `parityShards` are parity.
+ */
+interface ChunkManifest {
+    /** Stable per-chunk ID (uuid-like). Useful for client-side resume / dedup. */
+    id: string;
+    /** Position of this chunk in the file (0-indexed). */
+    chunkIndex: number;
+    /** Plaintext byte length of the chunk before encryption. */
+    originalSize: number;
+    /** AES-GCM ciphertext byte length (originalSize + 16 for the tag). */
+    ciphertextSize: number;
+    /** Number of RS data shards. */
+    dataShards: number;
+    /** Number of RS parity shards. */
+    parityShards: number;
+    /** Length in bytes of every shard (data and parity are equal). */
+    shardSize: number;
+    /** SHA-256 (hex) of each shard's ciphertext bytes, in shard order. */
+    shardHashes: string[];
+    /** Per-chunk AES-256-GCM key + IV. Plain in the manifest — gating happens at the SpaceDO. */
+    cipher: ChunkKeyMaterial;
+}
+/**
+ * Top-level manifest for a single stored file. Persisted in the user's
+ * SharedSpace by file id; readable / writable per the space's ACL.
+ */
+interface FileManifest {
+    /** Stable file ID. Assigned by the SDK at write time; used to read or delete. */
+    id: string;
+    /** Human-readable filename (display only — not used by the shard store). */
+    name: string;
+    /** Total plaintext byte length. Sum of chunk `originalSize`s. */
+    size: number;
+    /** MIME type the application supplied at write time. Opaque to storage. */
+    type: string;
+    /** Optional virtual path / folder hint for the application. */
+    path?: string;
+    /** When the file was last modified per the application (ms epoch). */
+    lastModified: number;
+    /** When this manifest was created on the SDK side (ms epoch). */
+    createdAt: number;
+    /** Ordered list of chunks. Concatenate them in index order to rebuild the file. */
+    chunks: ChunkManifest[];
+    /** SDK schema version. Bump on breaking manifest-shape changes. */
+    version: 1;
+}
+/**
+ * Lightweight summary returned by `FileStorage.writeFile` and surfaced in
+ * directory-style listings. The full manifest is only fetched when actually
+ * reassembling the file.
+ */
+interface FileStat {
+    id: string;
+    name: string;
+    size: number;
+    type: string;
+    path?: string;
+    lastModified: number;
+    createdAt: number;
+    chunkCount: number;
+    shardCount: number;
+}
+/** Distil a `FileManifest` into a `FileStat`. */
+declare function manifestToStat(manifest: FileManifest): FileStat;
+
+/**
+ * HTTP client for the open content-addressed shard store.
+ *
+ * Each shard is named by the lowercase hex SHA-256 of its ciphertext bytes.
+ * The server verifies the hash on PUT, so the address authenticates the
+ * contents — there's no benefit to ACLing PUT/GET, and making them open
+ * enables cross-user dedup down the line.
+ *
+ * Wire protocol:
+ *   PUT  /api/shards/:hash    body: shard bytes (application/octet-stream)
+ *                             200 { ok: true, hash, size, dedup: boolean }
+ *                             400 if hash doesn't match body
+ *
+ *   GET  /api/shards/:hash    200 with shard bytes (application/octet-stream)
+ *                             404 if absent
+ *
+ *   HEAD /api/shards/:hash    200 if present (no body) — used by callers to
+ *                             skip a PUT they'd otherwise dedup-rewrite. The
+ *                             server can ignore the optimization if it wants.
+ */
+interface ShardClientOptions {
+    /** Base URL of the accelerator (e.g. `https://muhkoo-accelerator.workers.dev`). */
+    baseUrl: string;
+    /**
+     * Path prefix for the shard endpoints, joined to `baseUrl` before the
+     * hash. Defaults to `/api/shards`, which targets a global shard store
+     * (e.g. a dedicated `ShardStoreDO`). Pass a room-scoped value like
+     * `/api/spaces/{roomId}/shards` to keep shards bound to a specific
+     * `SharedSpaceDO` — that's the path the chat application uses today.
+     *
+     * Leading slash optional; trailing slash stripped. The final URL is
+     * always `${baseUrl}${normalizedPrefix}/${encodeURIComponent(hash)}`.
+     */
+    pathPrefix?: string;
+    /**
+     * Optional custom fetch implementation. Defaults to `globalThis.fetch`.
+     * Provided so callers can inject retries / auth / instrumentation.
+     */
+    fetch?: typeof fetch;
+}
+/**
+ * Compute the lowercase hex SHA-256 of `bytes`. Available via WebCrypto in
+ * every runtime this SDK targets.
+ */
+declare function shardHash(bytes: Uint8Array): Promise<string>;
+declare class ShardClient {
+    private readonly baseUrl;
+    private readonly pathPrefix;
+    private readonly fetchFn;
+    constructor(opts: ShardClientOptions);
+    /** Build the URL for a given shard hash — exposed for callers that want to log or pre-resolve. */
+    urlForHash(hash: string): string;
+    /**
+     * Upload a shard. The server verifies SHA-256(body) matches `:hash` and
+     * rejects with 400 if not, so the caller is the source of truth on
+     * naming. Re-uploading an existing shard is idempotent — the server
+     * returns `dedup: true` in that case.
+     */
+    putShard(hash: string, bytes: Uint8Array): Promise<{
+        dedup: boolean;
+    }>;
+    /**
+     * Fetch a shard by hash. Throws if the server returns a non-200; returns
+     * `null` for 404 so callers can distinguish "missing" from "errored".
+     */
+    getShard(hash: string): Promise<Uint8Array | null>;
+    /**
+     * 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
+     * JSON body — we don't depend on either.
+     */
+    hasShard(hash: string): Promise<boolean>;
+}
+
+/**
+ * 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 }
+ */
+
+interface SharedSpaceClientOptions {
+    /** Base URL of the accelerator. */
+    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`). */
+    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. */
+    writeFileManifest(spaceId: string, manifest: FileManifest): Promise<void>;
+    /** Read a file manifest by id. Requires `read` permission. */
+    readFileManifest(spaceId: string, fileId: string): Promise<FileManifest>;
+    /** Delete a file manifest by id. Requires `delete` permission. */
+    deleteFileManifest(spaceId: string, fileId: string): Promise<boolean>;
+    /** List file summaries in the space. Requires `read` permission. */
+    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 jsonRequest;
+}
+
+/**
+ * `FileStorage` — top-level entry point for chunked, encrypted, erasure-coded
+ * file storage.
+ *
+ * Pipeline for writing a file:
+ *   1. Split the plaintext into fixed-size chunks (default 4 MiB).
+ *   2. For each chunk:
+ *        a. Generate a fresh AES-256-GCM key + 12-byte IV (`ChunkCipher`).
+ *        b. Encrypt the chunk → ciphertext (plaintext.length + 16 bytes tag).
+ *        c. Reed–Solomon encode the ciphertext into `dataShards + parityShards`
+ *           equal-length shards (`ReedSolomonCodec`).
+ *        d. PUT every shard to the content-addressed shard store, keyed by
+ *           SHA-256 of the shard bytes (`ShardClient`).
+ *   3. Build a `FileManifest` listing every chunk's keys, IVs, sizes, and
+ *      the SHA-256 of every shard in order.
+ *
+ * Two ways to use the manifest:
+ *   - {@link FileStorage.writeFileToShards} returns it to the caller, who is
+ *     then responsible for delivering it to readers (e.g. by E2E-encrypting
+ *     it as a chat message). The chat application takes this path.
+ *   - {@link FileStorage.writeFile} additionally POSTs the manifest to a
+ *     gated multi-user space (`SharedSpaceClient`) so any participant of the
+ *     space can read the file by manifest id later.
+ *
+ * Reading is the inverse: {@link FileStorage.readFileFromShards} takes a
+ * manifest and reassembles the plaintext; {@link FileStorage.readFile} first
+ * fetches the manifest from the space.
+ */
+
+interface FileStorageOptions {
+    /** Talks to the content-addressed shard store. Always required. */
+    shards: ShardClient;
+    /**
+     * Talks to the gated multi-user space holding manifests + ACLs.
+     * Optional — only required by {@link FileStorage.writeFile} /
+     * {@link FileStorage.readFile} / {@link FileStorage.deleteFile} /
+     * {@link FileStorage.listFiles} / {@link FileStorage.readManifest}.
+     *
+     * Callers that ship the manifest themselves (e.g. via an encrypted chat
+     * message) can omit `space` and use the `*FromShards` / `*ToShards`
+     * methods directly.
+     */
+    space?: SharedSpaceClient;
+    /**
+     * Plaintext chunk size in bytes. After encryption each chunk gains 16
+     * bytes (GCM tag); after RS encoding the size is rounded up to a multiple
+     * of `dataShards` per chunk. Default 4 MiB — a balance between
+     * round-trip cost and parallelism on the upload path.
+     */
+    chunkSize?: number;
+    /** RS data shards per chunk (default 4). */
+    dataShards?: number;
+    /** RS parity shards per chunk (default 2). */
+    parityShards?: number;
+    /**
+     * Cap on concurrent shard uploads / downloads. Tune for the network. The
+     * default of 8 saturates most home connections without overwhelming the
+     * server's per-IP rate limiter.
+     */
+    concurrency?: number;
+    /**
+     * Optional pre-compiled RS WebAssembly module. Defaults to the bundled
+     * loader. Pass this in environments where the bundled loader path isn't
+     * available (vitest, deploy-time-precompiled CF Workers).
+     */
+    rsWasmModule?: WebAssembly.Module;
+}
+/**
+ * Input to {@link FileStorage.writeFile} (which writes the manifest to a
+ * `SharedSpaceClient`). Carries the destination `spaceId`.
+ */
+interface WriteFileInput extends WriteToShardsInput {
+    /** Space to write the manifest to — must allow the caller `write`. */
+    spaceId: string;
+}
+/**
+ * Input to {@link FileStorage.writeFileToShards} (which doesn't write a
+ * manifest anywhere — that's the caller's job).
+ */
+interface WriteToShardsInput {
+    /** Raw data, a Blob, or a File. */
+    data: Uint8Array | Blob | File;
+    /** Application-supplied display metadata. */
+    metadata: {
+        name: string;
+        type: string;
+        path?: string;
+        lastModified?: number;
+    };
+    /**
+     * Optional pre-allocated file id. Defaults to a fresh one. Useful for
+     * resumable uploads: the same id always maps to the same manifest slot.
+     */
+    fileId?: string;
+}
+declare class FileStorage {
+    private readonly space;
+    private readonly shards;
+    private readonly chunkSize;
+    private readonly dataShards;
+    private readonly parityShards;
+    private readonly concurrency;
+    private readonly cipher;
+    private readonly codec;
+    private readonly rsWasmModule?;
+    constructor(opts: FileStorageOptions);
+    /**
+     * Chunk → encrypt → encode → upload-shards. Returns the resulting manifest
+     * along with a `FileStat` summary. The caller is responsible for storing
+     * or transmitting the manifest however it likes.
+     */
+    writeFileToShards(input: WriteToShardsInput): Promise<{
+        manifest: FileManifest;
+        stat: FileStat;
+    }>;
+    /**
+     * Inverse of {@link writeFileToShards}. Takes a manifest the caller
+     * obtained somehow (chat message, share link, etc.) and reassembles the
+     * plaintext. Throws if too many shards are missing or any chunk's auth
+     * tag fails.
+     */
+    readFileFromShards(manifest: FileManifest): Promise<{
+        data: Uint8Array;
+        stat: FileStat;
+    }>;
+    /** As {@link writeFileToShards}, plus POSTs the manifest to `input.spaceId`. */
+    writeFile(input: WriteFileInput): Promise<FileStat>;
+    /** As {@link readFileFromShards}, but fetches the manifest from a space first. */
+    readFile(spaceId: string, fileId: string): Promise<{
+        data: Uint8Array;
+        stat: FileStat;
+    }>;
+    /**
+     * Delete the manifest from a space. **Does not GC the shards** — those
+     * are content-addressed and may be referenced by other manifests.
+     * Garbage collection is a separate server-side concern (Phase D / D-ish).
+     */
+    deleteFile(spaceId: string, fileId: string): Promise<boolean>;
+    /** Convenience pass-through. */
+    listFiles(spaceId: string): Promise<FileStat[]>;
+    /** Read a manifest verbatim — useful for "share file" / export flows. */
+    readManifest(spaceId: string, fileId: string): Promise<FileManifest>;
+    private requireSpace;
+    /** Encrypt + encode + upload one chunk; return its manifest entry. */
+    private writeChunk;
+    /** Inverse of `writeChunk`. */
+    private readChunk;
+    /** Run `tasks` with at most `this.concurrency` in flight. */
+    private runWithConcurrency;
+}
+
+/**
+ * Reed–Solomon erasure-coding codec.
+ *
+ * Wraps the WASM-backed `encode` / `reconstruct` primitives in `wasm/rs.ts`
+ * with shard-padding bookkeeping so callers can hand it any-length input and
+ * get back uniform-size shards.
+ *
+ * Usage:
+ *   const codec = new ReedSolomonCodec();
+ *   await codec.ready();
+ *   const { shards, shardSize, originalSize } = codec.encode(plaintext, 4, 2);
+ *   // 6 shards (4 data + 2 parity), each `shardSize` bytes
+ *   // …ship them, lose up to 2, then …
+ *   const recovered = codec.decode(shards, 2, deadIndexes, originalSize);
+ *
+ * Why the explicit `originalSize`: RS pads input to make every data shard the
+ * same length. The decoder must trim that padding back off after recovery.
+ * The caller is responsible for stashing `originalSize` somewhere durable
+ * (the file manifest, in this codebase).
+ */
+interface EncodeResult {
+    /** All `dataShards + parityShards` shards. All have length `shardSize`. */
+    shards: Uint8Array[];
+    /** Length of every shard (data and parity). */
+    shardSize: number;
+    /** Length of the original input before padding. Needed to trim on decode. */
+    originalSize: number;
+    /** How many of the leading shards are data (the rest are parity). */
+    dataShards: number;
+    /** How many parity shards trail the data shards. */
+    parityShards: number;
+}
+declare class ReedSolomonCodec {
+    /**
+     * Resolves once the WASM module is loaded; safe to call repeatedly.
+     *
+     * Pass `wasmModule` to use a pre-compiled module (e.g. in tests where the
+     * rollup-inlined loader path isn't available, or in CF Workers where you
+     * want to load the module at deploy time). Default path uses the bundled
+     * base64-inlined wasm — works in Node, browsers, and Workers.
+     */
+    ready(wasmModule?: WebAssembly.Module): Promise<void>;
+    /**
+     * Split `data` into `dataShards` equal-size chunks (zero-padded to fit),
+     * compute `parityShards` parity shards, and return all of them.
+     */
+    encode(data: Uint8Array, dataShards: number, parityShards: number): EncodeResult;
+    /**
+     * Reconstruct the original `data` from `shards`. Up to `parityShards`
+     * shards may be missing; for each missing shard, pass an empty
+     * `Uint8Array` placeholder at its position and list the position in
+     * `deadShardIndexes`.
+     *
+     * `originalSize` is required so the trailing zero-padding can be trimmed.
+     */
+    decode(shards: Uint8Array[], parityShards: number, deadShardIndexes: number[], originalSize: number): Uint8Array;
+}
+
+/**
+ * Universal wasm-bindgen glue for `wasm-reed-solomon-erasure` (v0.2.2 — Rust
+ * Reed–Solomon erasure-coding library compiled with `wasm-pack --target nodejs`).
+ *
+ * The upstream npm package ships `wasm_reed_solomon_erasure.js` which uses
+ * `require('fs').readFileSync()` to load the WASM file at module load time —
+ * that hard-codes Node and breaks browsers / CF Workers. This file is a port
+ * of that glue with the Node-only pieces removed:
+ *
+ *   - `TextDecoder` is taken from the global (available in Node 12+, every
+ *     modern browser, and Workers — no `require('util')`).
+ *   - The WASM module is loaded via the rollup-inlined `.wasm` import, the
+ *     same `targetEnv: 'auto-inline'` path the bn128 verifier uses. Works in
+ *     Node, browser, and Workers without runtime fs access.
+ *
+ * Only the two public functions consumers actually need (`encode` and
+ * `reconstruct`) are exported. The rest is the wbindgen heap-table dance.
+ *
+ * Encoding:
+ *   `encode(dataShards: Uint8Array[], parityShard: number)` → array of
+ *   `dataShards.length + parityShard` Uint8Arrays. The first N are the input
+ *   shards unchanged; the trailing M are the freshly computed parity shards.
+ *   All shards are the same length — caller is responsible for padding the
+ *   data into equal-size data shards.
+ *
+ * Reconstruction:
+ *   `reconstruct(corruptedShards, parityShard, deadIndexes)` → fully recovered
+ *   array. Pass placeholders (empty Uint8Arrays) at the dead indexes; the
+ *   reconstructor fills them in. Up to `parityShard` shards may be missing.
+ */
+/**
+ * Load and instantiate the WASM module. Idempotent — repeated calls await the
+ * same one-shot promise.
+ *
+ * Two ways to initialize, matching the pattern used by `workers/groth16-verifier`:
+ *   1. `await initRsWasm()` — uses the bundled .wasm (base64-inlined at build
+ *      time by `@rollup/plugin-wasm`). Works in any runtime that allows
+ *      runtime `WebAssembly.compile()`.
+ *   2. `await initRsWasm(myWasmModule)` — accepts a pre-compiled
+ *      `WebAssembly.Module`. Useful when the bundled loader path isn't
+ *      available (vitest, CF Workers wanting deploy-time precompile, etc.).
+ */
+declare function initRsWasm(wasmModule?: WebAssembly.Module): Promise<void>;
+
+/**
+ * HTTP client for the accelerator's `/api/auth/*` endpoints.
+ *
+ * Owns the wire shapes for register / challenge / authenticate / verify so
+ * the React SPA (and any future consumers) don't reimplement them. The ZK
+ * identity derivation + Groth16 proof generation stay on the application
+ * side — this client handles only the round-trips.
+ *
+ * Mirrors `PersonalSpaceClient` / `ShardClient` / `SharedSpaceClient`: takes
+ * a `baseUrl`, optional custom `fetch`, throws typed `Error`s on failure
+ * (with the worker's message inlined where available).
+ */
+
+interface ZkRegisterRequest {
+    username: string;
+    /** Decimal-string Poseidon commitment. */
+    commitment: string;
+    /** Base64-encoded raw uncompressed ECDH public key (SEC1 0x04‖X‖Y). */
+    ecdhPublicKey: string;
+    /** Base64-encoded raw uncompressed ECDSA public key. */
+    ecdsaPublicKey: string;
+    email?: string | null;
+}
+interface ZkRegisterResponse {
+    success: boolean;
+}
+interface ZkChallengeResponse {
+    challengeId: string;
+    /** Hex-encoded random nonce — caller reduces into a BN254 field element for the proof. */
+    nonce: string;
+    /** Decimal-string Poseidon commitment the server has on file for this user. */
+    commitment: string;
+}
+interface ZkAuthenticateRequest {
+    challengeId: string;
+    proof: {
+        commitment: string;
+        /** Original hex nonce from the challenge (NOT the field-reduced version). */
+        nonce: string;
+        response: {
+            proof: Groth16Proof;
+            publicSignals: string[];
+        };
+        /** Base64 ECDSA-SHA256 signature over `JSON.stringify(response.proof)`. */
+        signature: string;
+    };
+    rememberMe?: boolean;
+}
+interface AuthSuccess {
+    token: string;
+    username: string;
+}
+interface AuthClientOptions {
+    /** Absolute URL of the accelerator worker (no trailing slash required). */
+    baseUrl: string;
+    /** Optional custom fetch — defaults to `globalThis.fetch`. */
+    fetch?: typeof fetch;
+}
+declare class AuthClient {
+    private readonly baseUrl;
+    private readonly fetchFn;
+    constructor(opts: AuthClientOptions);
+    /** Submit ZK registration. Caller has already derived the identity + commitment. */
+    register(req: ZkRegisterRequest): Promise<ZkRegisterResponse>;
+    /** Request an auth challenge for `username` (server issues a fresh nonce). */
+    getChallenge(username: string): Promise<ZkChallengeResponse>;
+    /** Trade a challenge + proof for a session token. */
+    authenticate(req: ZkAuthenticateRequest): Promise<AuthSuccess>;
+    /**
+     * Validate a previously stored session token. Returns `{ username }` on
+     * success; throws on 401/404 — caller uses that to drop a stale token
+     * when restoring a session after a reload.
+     */
+    verify(token: string): Promise<{
+        username: string;
+    }>;
+    private json;
+    private parse;
+}
+
+/**
+ * Deterministic ZK identity derivation from `(username, password)`.
+ *
+ * Same inputs on ANY device produce the same secret, salt, and P-256
+ * ECDSA + ECDH keypairs — which is what makes federated login from a
+ * fresh browser possible. There is no localStorage involvement: every
+ * register and login call re-derives the identity on demand.
+ *
+ * Pipeline:
+ *   master_seed = PBKDF2-SHA256(password, "muhkoo-zk-v1:" || username, 200k iters)
+ *   secret      = HKDF-Expand-SHA256(master_seed, "zk-secret",  32 bytes) → hex
+ *   salt        = HKDF-Expand-SHA256(master_seed, "zk-salt",    32 bytes) → hex
+ *   ecdsa_priv  = HKDF-Expand-SHA256(master_seed, "ecdsa-priv", 32 bytes)
+ *   ecdh_priv   = HKDF-Expand-SHA256(master_seed, "ecdh-priv",  32 bytes)
+ *
+ * P-256 public points are computed via `@noble/curves` (WebCrypto has no
+ * derive-public-from-private-scalar API), then both keypairs are imported
+ * into SubtleCrypto in JWK form so the rest of the crypto stack can keep
+ * using `crypto.subtle.sign` / `crypto.subtle.deriveBits`.
+ *
+ * Originally lived in `accelerator/public/js/zk-identity.js` and was ported
+ * to `muhkoo/web/src/zk/identity.ts`; consolidated here so the SDK owns
+ * identity derivation end-to-end.
+ */
+interface ZkIdentity {
+    /** 32-byte secret, hex-encoded. Private witness for the ZK circuit. */
+    secretHex: string;
+    /** 32-byte salt, hex-encoded. Private witness for the ZK circuit. */
+    saltHex: string;
+    /** P-256 ECDSA keypair, used to sign auth proofs. */
+    ecdsaKeyPair: CryptoKeyPair;
+    /** P-256 ECDH keypair, used by the chat ratchet. */
+    ecdhKeyPair: CryptoKeyPair;
+}
+/**
+ * Derive a deterministic ZK identity from `(username, password)`.
+ *
+ * Same inputs always produce the same identity, on any device — that's
+ * what makes federated login work without dragging encrypted state across
+ * devices.
+ */
+declare function deriveIdentity(username: string, password: string): Promise<ZkIdentity>;
+
+/**
+ * Poseidon hash wrapper used by the ZK auth flow.
+ *
+ * Backed by `circomlibjs`'s `buildPoseidon`. Builder is lazy and cached
+ * because the JS-side Babyjubjub field reps take ~100ms to construct, and
+ * we'd rather not pay that on every page load.
+ *
+ * Returns hashes as decimal-string BigInts — same format snarkjs and the
+ * `preimagePoK` circuit expect for inputs.
+ *
+ * Note: circomlibjs is `optionalDependencies` in connect's package.json.
+ * Consumers that use the ZK auth flow (browser/server, not workers) need
+ * it installed. The workers build does not import this module.
+ */
+/**
+ * Poseidon-hash `inputs` and return the result as a decimal-string BigInt.
+ * Inputs are converted to BigInt — pass either bigints, numbers, or numeric
+ * strings.
+ */
+declare function poseidonHash(inputs: Array<bigint | string | number>): Promise<string>;
+
+/**
+ * Groth16 proof generation for the `preimagePoK` circuit.
+ *
+ * The circuit proves knowledge of `(secret, salt, ecdsaPub)` such that
+ *   commitment = Poseidon(secret, salt, Poseidon(ecdsaPub))
+ * while only revealing `(commitment, nonce, ecdsaPubHash)` as public signals.
+ *
+ * Circuit assets (wasm + zkey) are served by the accelerator worker. Their
+ * URLs are a required argument of {@link generateAuthProof} — there is no
+ * default. The web app constructs them relative to its configured worker
+ * `baseUrl` so the SPA can target either the local wrangler dev or a deployed
+ * worker depending on `VITE_WORKER_URL`.
+ */
+
+interface CircuitUrls {
+    /** preimagePoK.wasm — the circuit's witness generator. */
+    wasmUrl: string;
+    /** preimagePoK_0001.zkey — the proving key. */
+    zkeyUrl: string;
+}
+/**
+ * Canonical {@link CircuitUrls} for the `preimagePoK` login circuit, anchored
+ * at a base URL where the accelerator serves the circuit assets out of
+ * `circuits/build/`. The filenames here are fixed by the circom build output
+ * (the witness generator lands inside a `preimagePoK_js/` directory); callers
+ * shouldn't hard-code them. `Client` uses this to default its `circuits`
+ * option, and `PersonalSpaceClient` consumers can pass `defaultCircuitUrls(baseUrl)`.
+ */
+declare function defaultCircuitUrls(baseUrl: string): CircuitUrls;
+/**
+ * Reduce any hex/decimal/byte input to a decimal-string field element in
+ * `[0, FIELD_SIZE)`. snarkjs and the `preimagePoK` circuit both want decimal
+ * strings; everything else gets normalized here.
+ *
+ * **Behavior is intentionally byte-for-byte compatible with the legacy
+ * `accelerator/public/js/zk-snarkjs-client.js#toField`.** Diverging produces
+ * different commitments than accounts registered via the legacy flow,
+ * which locks those users out forever — the worker stores whatever
+ * commitment the client sent at register time and compares it as a string
+ * at login time.
+ *
+ * In particular: a 32+ char string of hex chars is always treated as hex,
+ * even if every character happens to be 0-9 with no a-f letters. An
+ * earlier version of this function gated the hex branch on "has at least
+ * one letter" — that broke the digit-only-hex edge case (rare in practice,
+ * but real). DO NOT add that letter check back.
+ */
+declare function toField(value: string | bigint | number): string;
+/**
+ * Build the user's Poseidon commitment binding `(secret, salt, ecdsaPubHash)`.
+ * Same formula the worker verifies against on register and authenticate.
+ */
+declare function buildCommitment(secretHex: string, saltHex: string, ecdsaPubHex: string): Promise<string>;
+/**
+ * Generate a Groth16 proof for the `preimagePoK` circuit. Public signals end
+ * up `[commitment, nonce, ecdsaPubHash]` — the worker checks the commitment
+ * matches the stored one and the nonce matches the issued challenge nonce
+ * reduced into the field.
+ *
+ * Throws if circuit URLs are unreachable or snarkjs decides the inputs are
+ * malformed.
+ */
+declare function generateAuthProof(args: {
+    secretHex: string;
+    saltHex: string;
+    ecdsaPubHex: string;
+    nonceHex: string;
+    /** Required — caller supplies URLs scoped to the worker they want to talk to. */
+    circuits: CircuitUrls;
+}): Promise<{
+    proof: Groth16Proof;
+    publicSignals: string[];
+    commitment: string;
+    nonceField: string;
+    ecdsaPubHash: string;
+}>;
+
+/**
+ * Conversions between SubtleCrypto `CryptoKey`s and the wire formats the
+ * accelerator's auth endpoints + `preimagePoK` circuit expect.
+ *
+ * Two outputs we need from an ECDSA `CryptoKey`:
+ *   - **base64 raw**  — passed to `/api/auth/zk-register` as
+ *                       `ecdsaPublicKey` / `ecdhPublicKey`. (Name is historical;
+ *                       the legacy client called it `exportPublicKeyToBase58`
+ *                       but actually used base64 — kept as base64.)
+ *   - **hex raw**     — fed to the proof as `ecdsaPub` input; the circuit
+ *                       reduces it into a field element.
+ *
+ * Both go through `crypto.subtle.exportKey("raw", ...)` which yields the
+ * uncompressed SEC1 form (`0x04 || X || Y`).
+ */
+/** Raw uncompressed (`0x04 || X || Y`) public key bytes, as lowercase hex. */
+declare function exportPublicKeyHex(publicKey: CryptoKey): Promise<string>;
+/** Raw uncompressed public key as base64 — wire format for the auth endpoints. */
+declare function exportPublicKeyBase64(publicKey: CryptoKey): Promise<string>;
+/** Sign a UTF-8 `message` with an ECDSA private key. Returns base64. */
+declare function signMessage(message: string, privateKey: CryptoKey): Promise<string>;
+
+/**
+ * `SessionState` — the in-memory source of truth for "who is signed in" on a
+ * {@link Client}.
+ *
+ * It separates two concerns that have different lifetimes and security
+ * properties:
+ *
+ *   - **session** (`{ token, username, commitment }`) — proves the user is
+ *     authenticated to the accelerator. Cheap to persist (the token is an
+ *     opaque server-side handle) and enough to authorize token-gated REST
+ *     calls. Restored from a {@link SessionStore} across reloads.
+ *
+ *   - **identity** ({@link ZkIdentity}) — the derived secret + keypairs. Lets
+ *     the client *prove* ownership (ZK), derive at-rest encryption keys, and
+ *     run the messaging ratchet. It is derived from `(username, password)` and
+ *     is deliberately **never** persisted by default — a restored session has
+ *     a valid token but no identity until the user re-derives it
+ *     (`client.auth.zk.unlock(password)`).
+ *
+ * This split is what makes `restore()` (authenticated, can't decrypt) and
+ * `unlock()` (now can decrypt) two distinct, intentional states.
+ */
+
+/** The persistable part of a session — safe-ish to keep across reloads. */
+interface StoredSession {
+    token: string;
+    username: string;
+    /** Decimal-string Poseidon commitment — the user's stable id. */
+    commitment: string;
+}
+/**
+ * Pluggable persistence for the session token. Browser apps typically back
+ * this with `localStorage`; the default is in-memory (lost on reload).
+ *
+ * Identity material is intentionally not part of this interface — see the
+ * class docs. Apps that want federated session restore without re-prompting
+ * for a password can persist it themselves and call `unlock()` on boot.
+ */
+interface SessionStore {
+    load(): StoredSession | null | Promise<StoredSession | null>;
+    save(session: StoredSession): void | Promise<void>;
+    clear(): void | Promise<void>;
+}
+/** Default in-memory store — holds the session for the process lifetime only. */
+declare class MemorySessionStore implements SessionStore {
+    private current;
+    load(): StoredSession | null;
+    save(session: StoredSession): void;
+    clear(): void;
+}
+/**
+ * A {@link SessionStore} backed by the browser's `localStorage`, so a session
+ * survives page reloads. This is the store most browser apps want — pass it to
+ * `new Client({ sessionStore: new LocalStorageSessionStore() })`.
+ *
+ * Browser-only: construction throws if `localStorage` is unavailable (Node,
+ * Workers, or SSR before hydration) — use {@link MemorySessionStore} or a
+ * custom store there. Keys are namespaced under `keyPrefix` so multiple apps
+ * on the same origin don't collide.
+ */
+declare class LocalStorageSessionStore implements SessionStore {
+    private readonly tokenKey;
+    private readonly usernameKey;
+    private readonly commitmentKey;
+    constructor(keyPrefix?: string);
+    load(): StoredSession | null;
+    save(session: StoredSession): void;
+    clear(): void;
+}
+/**
+ * The {@link SessionStore} a {@link Client} uses when none is supplied: a
+ * {@link LocalStorageSessionStore} in the browser (so sessions survive
+ * reloads), falling back to {@link MemorySessionStore} anywhere `localStorage`
+ * is unavailable or unusable (Node, Workers, SSR, or private-mode browsers
+ * that throw on access). Pass an explicit store to override.
+ */
+declare function defaultSessionStore(keyPrefix?: string): SessionStore;
+declare class SessionState {
+    private session;
+    private _identity;
+    private readonly store;
+    constructor(store?: SessionStore);
+    /** True once a token-bearing session exists (regardless of identity). */
+    get isAuthenticated(): boolean;
+    /** True once identity material is available (login or unlock happened). */
+    get isUnlocked(): boolean;
+    get token(): string | null;
+    get username(): string | null;
+    get commitment(): string | null;
+    get identity(): ZkIdentity | null;
+    /** Identity material, throwing a clear error when the client is locked. */
+    requireIdentity(): ZkIdentity;
+    /** Persist + hold a freshly authenticated session. */
+    setSession(session: StoredSession): Promise<void>;
+    /** Attach derived identity material to the current session. */
+    setIdentity(identity: ZkIdentity): void;
+    /** Load a persisted session (used by `restore()`); identity stays null. */
+    loadPersisted(): Promise<StoredSession | null>;
+    /** Drop all session + identity state and clear persistence. */
+    clear(): Promise<void>;
+}
+
+/**
+ * `client.auth` — user authentication, exposed today through the `zk`
+ * sub-namespace (`client.auth.zk.login(...)`). Leaving room under `auth` for
+ * other strategies later (e.g. `auth.oauth`) without reshaping the surface.
+ *
+ * `ZkAuth` absorbs the full ZK register/login dance that used to live in the
+ * web app's `AuthContext`:
+ *
+ *   register:  derive identity → commitment → POST /api/auth/zk-register
+ *   login:     derive identity → challenge → Groth16 proof → sign →
+ *              POST /api/auth/zk-authenticate → session token
+ *
+ * The derived {@link ZkIdentity} (secret + ECDSA/ECDH keypairs) is held in
+ * {@link SessionState} so the storage + message namespaces can reuse it for
+ * at-rest encryption and the messaging ratchet without re-deriving.
+ */
+
+/** What the auth methods resolve to — the stable, non-secret user facts. */
+interface AuthUser {
+    username: string;
+    /** Decimal-string Poseidon commitment — the user's stable id. */
+    commitment: string;
+}
+interface RegisterParams {
+    username: string;
+    password: string;
+    email?: string | null;
+    /** Sign in immediately after registering (default: true). */
+    login?: boolean;
+}
+interface LoginOptions {
+    /** Ask the accelerator for a long-lived (30d) session (default: false). */
+    rememberMe?: boolean;
+}
+interface ZkAuthDeps {
+    auth: AuthClient;
+    circuits: CircuitUrls;
+    session: SessionState;
+}
+/**
+ * ZK identity auth. One instance per {@link Client}; reads/writes the shared
+ * {@link SessionState}.
+ */
+declare class ZkAuth {
+    private readonly deps;
+    constructor(deps: ZkAuthDeps);
+    /**
+     * Register a new user, then (by default) sign them in. The identity is
+     * derived deterministically from `(username, password)` — the same inputs
+     * reproduce it on any device, so there's no key material to ship around.
+     */
+    register(params: RegisterParams): Promise<AuthUser>;
+    /**
+     * Sign in: re-derive the identity, prove knowledge of it against a fresh
+     * server challenge, and trade the proof for a session token. On success
+     * both the session and the identity are stored on the client.
+     */
+    login(username: string, password: string, opts?: LoginOptions): Promise<AuthUser>;
+    /**
+     * Restore a persisted session on boot. Validates the stored token with the
+     * accelerator; returns the user when valid, or `null` (and clears the
+     * stale session) otherwise. Identity stays locked — call {@link unlock}
+     * to re-enable encryption/messaging without a full re-login.
+     */
+    restore(): Promise<AuthUser | null>;
+    /**
+     * Re-derive identity material for an already-authenticated (restored)
+     * session, so the client can decrypt storage and run the ratchet. Verifies
+     * the password by checking the derived commitment matches the session's.
+     */
+    unlock(password: string): Promise<void>;
+    /** Sign out: clears the session, identity, and persisted token. */
+    logout(): Promise<void>;
+    /** The signed-in user, or `null`. Synchronous read of current state. */
+    get user(): AuthUser | null;
+    /**
+     * The derived identity material for the current session, or `null` when
+     * locked. Exposed so apps that still drive lower-level primitives (e.g. a
+     * chat ratchet keyed off the same identity) can reuse it without
+     * re-deriving from the password.
+     */
+    get identity(): ZkIdentity | null;
+    /** The current session token, or `null` when signed out. */
+    get token(): string | null;
+    /** Poseidon commitment for an identity — the value the server stores. */
+    private commitmentFor;
+}
+/** `client.auth` — the auth namespace. Strategies hang off here. */
+declare class AuthNamespace {
+    readonly zk: ZkAuth;
+    constructor(deps: ZkAuthDeps);
+    /** Convenience pass-through: the currently signed-in user, or `null`. */
+    get user(): AuthUser | null;
+}
+
+/**
+ * `HttpClient` — the one place the unified {@link Client} talks to the
+ * accelerator over HTTP.
+ *
+ * Every request carries two independent credentials:
+ *   - the **app key** (`mk_…`) on `X-Muhkoo-Key` — resolves the app /
+ *     developer / env context the accelerator uses for routing + billing;
+ *   - the **user session token** on `X-Muhkoo-Session` (when a user is
+ *     logged in) — the accelerator validates it and injects a trusted
+ *     `X-Muhkoo-User-Context` downstream so per-user spaces can authorize
+ *     the request without a fresh Groth16 proof.
+ *
+ * `X-Muhkoo-Key` is used (rather than `Authorization: Bearer`) because it is
+ * a non-forbidden header that skips the CORS preflight in browsers.
+ *
+ * The class exposes a header-injecting {@link fetch} that can be handed to
+ * lower-level building blocks (`AuthClient`, `PersonalSpaceClient`) so they
+ * keep owning their own wire shapes while still getting the credentials, plus
+ * convenience JSON helpers (`get`/`post`/`del`) for code that talks to the
+ * accelerator directly.
+ */
+interface HttpClientOptions {
+    /** Absolute URL of the accelerator worker (trailing slash optional). */
+    baseUrl: string;
+    /**
+     * App / publishable key, e.g. `mk_test_pk_…`. Sent on every request as
+     * `X-Muhkoo-Key` when present. Transitionally optional (auth + personal
+     * storage still function without it), but the product direction is to
+     * REQUIRE it — it attributes traffic for billing/metering and authorizes
+     * shared-space (messaging) websockets.
+     */
+    apiKey?: string;
+    /** Returns the current user session token, or `null` when logged out. */
+    getSessionToken?: () => string | null;
+    /** Custom fetch — defaults to `globalThis.fetch`. */
+    fetch?: typeof fetch;
+}
+/** Thrown for any non-2xx accelerator response. Carries the HTTP status. */
+declare class HttpError extends Error {
+    readonly status: number;
+    readonly body?: unknown | undefined;
+    constructor(message: string, status: number, body?: unknown | undefined);
+}
+declare class HttpClient {
+    readonly baseUrl: string;
+    private readonly apiKey;
+    private readonly getSessionToken;
+    private readonly fetchFn;
+    constructor(opts: HttpClientOptions);
+    /**
+     * A `fetch`-compatible function that injects the app key + session token
+     * headers. Hand this to `AuthClient` / `PersonalSpaceClient` so they pick
+     * up credentials without knowing about them.
+     */
+    readonly fetch: typeof fetch;
+    get<T = unknown>(path: string): Promise<T>;
+    post<T = unknown>(path: string, body?: unknown): Promise<T>;
+    del<T = unknown>(path: string, body?: unknown): Promise<T>;
+    private request;
+}
+
+/**
+ * `client.storage` — per-user persistent 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
+ *
+ * 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
+ * (stamped on every request by {@link HttpClient}) — no per-op Groth16 proof.
+ *
+ * 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.
+ *
+ * `query()` is intentionally deferred — see the SDK overhaul plan.
+ */
+
+interface StorageNamespaceDeps {
+    http: HttpClient;
+    session: SessionState;
+    /** WebSocket base (ws/wss) for the change feed; derived from baseUrl. */
+    wsBaseUrl: string;
+}
+interface SetOptions {
+    /** Encrypt the value at rest (default: true). */
+    encrypt?: boolean;
+}
+interface StorageChangeEvent<T = unknown> {
+    collection: string;
+    id: string;
+    type: "set" | "delete";
+    /** The decrypted value for `set`; `null` for `delete`. */
+    data: T | null;
+}
+declare class StorageNamespace {
+    private readonly deps;
+    private cipher;
+    private cipherIdentity;
+    constructor(deps: StorageNamespaceDeps);
+    /** 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. */
+    get<T = unknown>(collection: string, id: string): Promise<T | null>;
+    /** Delete `collection`/`id`. Returns whether the key existed. */
+    delete(collection: string, id: string): Promise<boolean>;
+    /** List the ids present in `collection`. */
+    list(collection: string): Promise<string[]>;
+    /** Reserved — server-side query is deferred (see the overhaul plan). */
+    query(_collection: string, _filter?: unknown): Promise<never>;
+    /**
+     * Subscribe to realtime changes to this user's data across devices. Opens
+     * the personal space's websocket and decrypts each change before handing
+     * it to `handler`. Returns an unsubscribe function.
+     *
+     * Requires a `WebSocket` global (browsers; Node 22+ or a `ws` shim).
+     */
+    on<T = unknown>(event: "change", handler: (e: StorageChangeEvent<T>) => void): () => void;
+    private dispatchChange;
+    /** Decode a stored value: decrypt envelopes, pass plaintext through. */
+    private decode;
+    private commitment;
+    private spacePath;
+    private kvPath;
+    /** The at-rest cipher for the current identity (re-derived if it changes). */
+    private getCipher;
+}
+
+/**
+ * `Room` — a client handle for one shared space (a chat-style room).
+ *
+ * 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.
+ *
+ * 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()`.
+ *
+ * `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(...)`.
+ */
+
+type Listener = (e: CustomEvent) => void;
+interface RoomFileMetadata {
+    name: string;
+    type: string;
+    path?: string;
+    lastModified?: number;
+}
+interface RoomDeps {
+    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). */
+    myId: () => string;
+    /** Resolves a short-lived WS upgrade ticket (or null when keyless). */
+    fetchTicket: () => Promise<string | null>;
+}
+declare class Room {
+    private readonly deps;
+    readonly name: string;
+    private channel;
+    private readonly pending;
+    constructor(deps: RoomDeps);
+    /** Open the room websocket (resolves the ticket + identity lazily). */
+    connect(): Promise<void>;
+    disconnect(): void;
+    /** Subscribe to a 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. */
+    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<{
+        manifest: FileManifest;
+        stat: FileStat;
+    }>;
+    /** Fetch + decode a file previously shared in this room. */
+    getFile(manifest: FileManifest): Promise<{
+        data: Uint8Array;
+        stat: FileStat;
+    }>;
+    private fileStorage;
+}
+
+/**
+ * `client.message` — realtime messaging over the shared-space primitive.
+ *
+ *   const sub = client.message.subscribe('todos', e => …)   // pub/sub feed
+ *   await client.message.publish('todos', data)
+ *   await client.message.send('user:abc', { text: 'Hello!' }) // E2E DM
+ *
+ * Two distinct modes, one transport (a shared-space room websocket via
+ * {@link BroadcastChannel}):
+ *
+ *   - **pub/sub** — `publish`/`subscribe(subject)` ride plaintext `pub` frames
+ *     the accelerator blind-relays to everyone in the room `pub:<subject>`.
+ *   - **direct messages** — `send('user:x', …)` is end-to-end encrypted via the
+ *     Double Ratchet, fanned out in the recipient's inbox room `inbox:x`;
+ *     the recipient receives them by `subscribe('user:x', …)` (their own id).
+ *
+ * Every room websocket is opened with a short-lived signed ticket fetched from
+ * `POST /api/ws-ticket` (browsers can't set the app-key header on
+ * `new WebSocket()`), then completes the room's `{name}` → `{ready}` handshake
+ * before any frame is sent.
+ */
+
+/** The subset of {@link BroadcastChannel} this namespace drives (test seam). */
+interface ChannelLike {
+    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;
+}
+interface MessageNamespaceDeps {
+    http: HttpClient;
+    session: SessionState;
+    /** WebSocket base (ws/wss); derived from the accelerator baseUrl. */
+    wsBaseUrl: string;
+    /** Test seam — defaults to constructing a real {@link BroadcastChannel}. */
+    createChannel?: (url: string, myId: string) => ChannelLike;
+}
+interface MuhkooMessageEvent<T = unknown> {
+    subject: string;
+    from: string;
+    data: T;
+}
+/** Handle returned by `subscribe`; call `.unsubscribe()` to detach. */
+interface MessageSubscription {
+    subject: string;
+    unsubscribe(): void;
+}
+declare class MessageNamespace {
+    private readonly deps;
+    /** One connection per room, memoized. */
+    private readonly rooms;
+    constructor(deps: MessageNamespaceDeps);
+    /**
+     * Subscribe to a subject (pub/sub) or to this user's own id (`user:<me>`)
+     * to receive direct messages. Returns an unsubscribe handle.
+     */
+    subscribe<T = unknown>(subject: string, handler: (e: MuhkooMessageEvent<T>) => void): MessageSubscription;
+    /** Publish `data` to every subscriber of `subject` (plaintext fan-out). */
+    publish<T = unknown>(subject: string, data: T): Promise<void>;
+    /**
+     * Send an end-to-end-encrypted direct message to `user:<id>`. Delivered in
+     * the recipient's inbox room; the recipient must be subscribed
+     * (`subscribe('user:<id>')`) and online to receive it (E2E requires a live
+     * ratchet between both parties).
+     */
+    send<T = unknown>(target: string, payload: T): Promise<void>;
+    /**
+     * Mint a new private shared-space id, server-side. The id MUST come from
+     * the accelerator: it's a 64-hex string that embeds the spaces DO class
+     * hash, which the worker validates on every subsequent request — client-
+     * generated ids would be rejected. Pass the returned id to {@link room}
+     * (or share it) to open the space.
+     */
+    createRoom(): Promise<string>;
+    /**
+     * Open a handle to a shared-space room — group E2E messaging plus
+     * room-scoped file storage. The websocket isn't opened until
+     * `room.connect()`; `room.putFile`/`getFile` work without it. This is the
+     * primitive group chat is built on (`publish`/`subscribe`/`send` are the
+     * higher-level conveniences layered over the same space transport).
+     */
+    room(roomName: string): Room;
+    /** Close every open room connection (e.g. on logout). */
+    disconnect(): void;
+    private getRoom;
+    private openRoom;
+    /** Fetch a short-lived WS upgrade ticket scoped to this app key. */
+    private fetchTicket;
+    private myId;
+}
+
+/** The hosted Muhkoo Accelerator — the default {@link ClientOptions.baseUrl}. */
+declare const DEFAULT_BASE_URL = "https://api.muhkoo.dev";
+interface ClientOptions {
+    /**
+     * App / publishable key issued by the accelerator (e.g. `mk_test_pk_…`).
+     *
+     * TRANSITIONALLY optional: auth + storage currently function without it so
+     * the in-tree web app can migrate before a key is provisioned. The product
+     * direction is that the app key becomes REQUIRED — it's how every app
+     * authenticates to the Accelerator and gets attributed for metering/billing.
+     * New integrations should always pass one.
+     */
+    apiKey?: string;
+    /**
+     * Absolute URL of the accelerator (trailing slash optional). Defaults to
+     * the hosted Muhkoo Accelerator ({@link DEFAULT_BASE_URL}); override to
+     * point at staging, a local `wrangler dev`, or a self-hosted deployment.
+     */
+    baseUrl?: string;
+    /**
+     * URLs of the `preimagePoK` circuit assets used for ZK login proofs.
+     * Defaults to {@link defaultCircuitUrls} anchored at `baseUrl` — i.e.
+     * `${baseUrl}/circuits/build/preimagePoK_js/preimagePoK.wasm` and
+     * `…/preimagePoK_0001.zkey`, where the accelerator serves them.
+     */
+    circuits?: CircuitUrls;
+    /** Pluggable session-token persistence. Defaults to in-memory. */
+    sessionStore?: SessionStore;
+    /** Custom fetch — defaults to `globalThis.fetch`. */
+    fetch?: typeof fetch;
+    /** Optional log level for the SDK logger. */
+    logLevel?: string;
+}
+declare class Client {
+    readonly baseUrl: string;
+    /** Authentication — `client.auth.zk.login(...)`, etc. */
+    readonly auth: AuthNamespace;
+    /** Per-user persistent storage — `client.storage.set(...)`, etc. */
+    readonly storage: StorageNamespace;
+    /** Realtime messaging — `client.message.subscribe(...)`, etc. */
+    readonly message: MessageNamespace;
+    private readonly session;
+    private readonly http;
+    constructor(options?: ClientOptions);
+    /** The currently signed-in user, or `null`. */
+    get user(): AuthUser | null;
+    /** Whether a token-bearing session is active. */
+    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 };