@muhkoo/connect 0.14.0-alpha.7 → 0.14.0-alpha.9

package/dist/connect.workers.d.ts

@@ -0,0 +1,1188 @@
+declare class Logger {
+    private prefix;
+    private logLevel;
+    private console;
+    private showCaller;
+    level: string;
+    constructor(prefix?: string, LOGLEVEL?: string, showCaller?: boolean);
+    private shouldLog;
+    /**
+     * Extract caller information from stack trace
+     */
+    private getCallerInfo;
+    /**
+     * Format caller info for display
+     */
+    private formatCallerInfo;
+    setLevel(level: string): void;
+    setShowCaller(show: boolean): void;
+    info(...args: any[]): void;
+    log(...args: any[]): void;
+    verbose(...args: any[]): void;
+    success(...args: any[]): void;
+    warn(...args: any[]): void;
+    error(...args: any[]): void;
+    debug(...args: any[]): void;
+    assert(condition?: boolean, ...data: any[]): void;
+    clear(): void;
+    count(label?: string): void;
+    countReset(label?: string): void;
+    dir(item?: any, options?: any): void;
+    dirxml(...data: any[]): void;
+    group(...data: any[]): void;
+    groupCollapsed(...data: any[]): void;
+    groupEnd(): void;
+    table(tabularData?: any, properties?: string[]): void;
+    time(label?: string): void;
+    timeEnd(label?: string): void;
+    timeLog(label?: string, ...data: any[]): void;
+    trace(...data: any[]): void;
+    profile(label?: string): void;
+    profileEnd(label?: string): void;
+    timeStamp(label?: string): void;
+}
+
+declare global {
+    interface Console {
+        success(...args: any[]): void;
+        verbose(...args: any[]): void;
+    }
+}
+
+/**
+ * The SDK's process-global logger.
+ *
+ * Eight modules under `src/` read a bare `appLogger` off `globalThis` rather
+ * than importing one (`src/crypto/{KeyStore,DoubleRatchet,DoubleRatchetManager,
+ * Authenticator}.ts`, `src/core/Client.ts`,
+ * `src/core/namespaces/HostedAuth.ts`, `src/events/EventCore.ts`), so the
+ * binding has to exist before any of them runs, and the `declare global` below
+ * is what makes that typecheck.
+ *
+ * This module is the single place that bootstrap happens. It previously lived
+ * inline in three entry files — `src/browser/index.ts`, `src/workers/index.ts`,
+ * and `src/core/index.ts` (which `src/server/index.ts` picked up as an import
+ * side effect) — three copies that could drift.
+ *
+ * `??=` makes it idempotent, so importing it from several entries in one
+ * process is safe and the first writer wins.
+ *
+ * KNOWN HAZARD: package.json declares `"sideEffects": false`, which entitles a
+ * tree-shaker to drop a module imported purely for effect. The entries import
+ * this one for its `export`s as well, so it survives today — but the durable
+ * fix is to convert those eight bare reads into real imports of `appLogger`
+ * from here, which removes the reliance on a global entirely.
+ */
+
+declare global {
+    var appLogger: InstanceType<typeof Logger>;
+}
+
+/**
+ * @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;
+}
+
+/**
+ * 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",
+    ONLINE = "online",
+    OFFLINE = "offline",
+    SYNCING = "syncing",
+    SYNC_PROGRESS = "sync_progress",
+    SYNC_COMPLETE = "sync_complete",
+    SYNC_ERROR = "sync_error"
+}
+/**
+ * @public
+ * EventCore is a static event emitter with singleton functionality for global event handling.
+ */
+declare class EventCore {
+    private static eventTarget;
+    /**
+     * `event -> (caller's handler -> the wrapper actually registered on the
+     * EventTarget)`. Two levels because one event can have many listeners and
+     * {@link off} must remove exactly the wrapper it registered for that caller.
+     */
+    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. `BroadcastChannel` 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;
+    /**
+     * Optional async provider for a FRESH connection URL, called before each
+     * RECONNECT. Use it when the URL carries a single-use/expiring credential
+     * (e.g. a one-time WS upgrade ticket): on reconnect the baked-in ticket is
+     * already consumed/expired, so without this the reconnect is rejected and the
+     * transport burns through its attempts. The initial connect uses `url` as-is.
+     */
+    urlProvider?: () => string | Promise<string>;
+    /**
+     * Stable identifier for this connection (a channel / space / personal-space
+     * id). Lifecycle + MESSAGE events are namespaced by it on the shared
+     * `EventCore` bus so concurrent transports (chat room A, room B, the storage
+     * feed, …) never receive each other's frames. Optional — a unique id is
+     * generated when omitted; pass a semantic one for clearer debugging.
+     */
+    id?: string;
+    /** Reconnect automatically after unexpected disconnect (default `true`). */
+    autoReconnect?: boolean;
+    /** Delay between reconnect attempts in ms (default `3000`). */
+    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;
+    /**
+     * Heartbeat interval in ms. While connected, a `pingFrame` is sent every
+     * interval to keep the socket warm (long-lived WebSockets get dropped by CF
+     * / intermediaries when idle) and to detect a silently-dead connection.
+     * Default `30000`. Set `0` to disable the heartbeat entirely.
+     */
+    heartbeatInterval?: number;
+    /**
+     * How long (ms) to wait for a `pongFrame` after sending a ping before
+     * treating the connection as dead and forcing a reconnect. Should be well
+     * under `heartbeatInterval`. Default `10000`.
+     */
+    heartbeatTimeout?: number;
+    /** Outbound keep-alive frame. Default `"ping"`. */
+    pingFrame?: string;
+    /**
+     * Inbound keep-alive ack. Matching frames are swallowed (never surfaced as a
+     * `MESSAGE`) and reset the liveness timer. Must match the server's
+     * auto-response. Default `"pong"`.
+     */
+    pongFrame?: string;
+}
+declare class WSTransport extends EventCore {
+    /**
+     * Per-instance event scope. `EventCore` is a process-global static emitter,
+     * so without namespacing every WSTransport would hear every other one's
+     * frames. We prefix each event with this transport's `id` and expose
+     * `on`/`off`/`emit` that scope transparently — callers still use the plain
+     * `EventCoreEvents` enum and only ever see their own connection's events.
+     */
+    readonly id: string;
+    readonly emit: (event: EventCoreEvents, data: unknown) => void;
+    readonly on: (event: EventCoreEvents, handler: EventListener | CallableFunction) => void;
+    readonly off: (event: EventCoreEvents, handler: EventListener | CallableFunction) => void;
+    private scopedEvent;
+    private url;
+    private urlProvider?;
+    private socket;
+    private _isConnected;
+    private _isConnecting;
+    private autoReconnect;
+    private reconnectDelay;
+    private maxReconnectAttempts;
+    private reconnectAttempts;
+    private reconnectTimeout;
+    private outboundQueue;
+    private maxQueueSize;
+    private heartbeatInterval;
+    private heartbeatTimeout;
+    private pingFrame;
+    private pongFrame;
+    private heartbeatTimer;
+    private pongTimer;
+    constructor(opts: WSTransportOptions);
+    /** Open the socket. Resolves when CONNECTED fires. Rejects on first error. */
+    connect(): Promise<void>;
+    /** 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;
+    /** Begin the keep-alive loop (no-op when disabled). */
+    private startHeartbeat;
+    /** Stop the keep-alive loop and clear any pending liveness deadline. */
+    private stopHeartbeat;
+    /**
+     * Send one ping and arm a liveness deadline. If no `pongFrame` arrives before
+     * `heartbeatTimeout`, the connection is considered dead and we force a
+     * reconnect — this is what catches a silently-dropped TCP connection that
+     * never fired `onclose` (the failure mode that "loses connection with the
+     * Accelerator" on long sessions).
+     */
+    private sendHeartbeat;
+    /**
+     * Tear down a connection we believe is dead and kick off reconnect, without
+     * waiting on the OS/browser to eventually fire `onclose` (which a half-open
+     * socket may never do). We detach the handlers first so the normal close path
+     * can't double-fire the reconnect.
+     */
+    private forceReconnect;
+    private scheduleReconnect;
+    private flushQueue;
+}
+
+/**
+ * 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.** 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>;
+
+export { AES_GCM_IV_BYTES, AES_GCM_KEY_BYTES, AES_GCM_TAG_BYTES, BroadcastChannel, BroadcastChannelEvents, ChunkCipher, DoubleRatchet, EncryptedSession, EventCore, EventCoreEvents, KeyStore, Message, Message as MessageDefault, PBKDF2_DEFAULT_ITERATIONS, PREIMAGE_POK_VERIFICATION_KEY, Packet, SerializeMessage, WSTransport, decorators, decryptAesGcm, deriveAesKeyFromPassphrase, deriveBitsHkdf, encryptAesGcm, getSubtle, initBn128Wasm, randomBytes, unwrapWithPassphrase, verifyGroth16, wrapWithPassphrase };
+export type { ACL, ACLEntry, AuthKeyPair, AuthType, Bn128WasmInstance, BroadcastChannelEvent, BroadcastChannelOptions, ChunkKeyMaterial, CipherFrame, CipherMessage, CipherMessageHeader, DehydratedKeypair, DehydratedKeys, ECDHCurve, Groth16Proof, IncomingFrame, KeyExchangeFrame, KeyPair, Keypair, MessageBody, MessageEvent, MessageHeaders, MessageOptions, OAuthProvider, PacketOptions, Participant, Permission, PermissionCheckRequest, PermissionCheckResult, PublicKeyJWK, RatchetState, ReceiveResult, Role, Session, SessionOptions, Subscription, UserIdentity, VerificationKey, WSMessage, WSMessageType, WSTransportOptions, WrappedPayload };