dandelion-mesh 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wenhao Ji <predator.ray@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,192 @@
+# <img src="https://github.com/predatorray/dandelion-mesh/blob/assets/Dandelion_40x40.png?raw=true" alt="Description of image" width="40" height="40"> Dandelion Mesh
+
+[![License](https://img.shields.io/github/license/predatorray/dandelion-mesh)](LICENSE)
+[![Build Status](https://img.shields.io/github/actions/workflow/status/predatorray/dandelion-mesh/ci.yml?branch=main)](https://github.com/predatorray/dandelion-mesh/actions)
+[![codecov](https://codecov.io/github/predatorray/dandelion-mesh/graph/badge.svg?token=KqwNV13MD4)](https://codecov.io/github/predatorray/dandelion-mesh)
+![NPM Version](https://img.shields.io/badge/npm-not_published-blue)
+
+Serverless mesh network for browsers using WebRTC.
+
+***Connect***, ***Broadcast***, and ***Sync State*** without a central server.
+
+## Overview
+
+`dandelion-mesh` is a fault-tolerant P2P service mesh library for browser applications.
+
+It combines:
+- WebRTC data channels for transport,
+- RSA hybrid encryption for private messaging,
+- and the Raft consensus algorithm for leader election and ordered log replication
+
+All without requiring a dedicated server.
+
+## Usage
+
+### Install
+
+```bash
+npm install dandelion-mesh # not published yet
+```
+
+### Basic example
+
+```ts
+import { PeerJSTransport, DandelionMesh } from 'dandelion-mesh';
+
+// Create a transport and mesh instance
+const transport = new PeerJSTransport({ peerId: 'alice' });
+const mesh = new DandelionMesh(transport, {
+  bootstrapPeers: ['bob', 'charlie'],
+});
+
+// Listen for events
+mesh.on('ready', (id) => {
+  console.log('My peer ID:', id);
+});
+
+mesh.on('message', (msg) => {
+  if (msg.type === 'public') {
+    console.log(`[${msg.sender}]: ${JSON.stringify(msg.data)}`);
+  }
+  if (msg.type === 'private') {
+    console.log(`[private from ${msg.sender}]: ${JSON.stringify(msg.data)}`);
+  }
+});
+
+mesh.on('leaderChanged', (leaderId) => {
+  console.log('Current leader:', leaderId);
+});
+
+mesh.on('peersChanged', (peers) => {
+  console.log('Connected peers:', peers);
+});
+
+// Send messages
+await mesh.sendPublic({ action: 'bet', amount: 100 });
+await mesh.sendPrivate('bob', { cards: ['Ah', 'Kd'] });
+```
+
+### Using localStorage for durable sessions
+
+```ts
+import {
+  PeerJSTransport,
+  DandelionMesh,
+  LocalStorageRaftLog,
+} from 'dandelion-mesh';
+
+const transport = new PeerJSTransport({ peerId: 'alice' });
+const mesh = new DandelionMesh(transport, {
+  bootstrapPeers: ['bob', 'charlie'],
+  raftLog: new LocalStorageRaftLog('my-game-room'),
+});
+
+// Raft state (term, votedFor, log) persists across page refreshes,
+// allowing a peer to rejoin and catch up from where it left off.
+```
+
+### Custom transport
+
+```ts
+import { Transport, DandelionMesh } from 'dandelion-mesh';
+
+class MyWebSocketTransport implements Transport {
+  // Implement the Transport interface with your own
+  // connection management and message passing logic.
+  // ...
+}
+
+const transport = new MyWebSocketTransport();
+const mesh = new DandelionMesh(transport);
+```
+
+## High-level architecture
+
+```mermaid
+graph TB
+    subgraph "dandelion-mesh"
+        direction TB
+        API["DandelionMesh API<br/><i>sendPublic() · sendPrivate() · on('message')</i>"]
+
+        subgraph layers [" "]
+            direction LR
+            RAFT["Raft Consensus<br/><i>Leader Election<br/>Log Replication</i>"]
+            CRYPTO["Crypto Service<br/><i>RSA-OAEP + AES-GCM<br/>Hybrid Encryption</i>"]
+        end
+
+        TRANSPORT["Transport Layer<br/><i>PeerJS (default) · pluggable</i>"]
+    end
+
+    API --> RAFT
+    API --> CRYPTO
+    CRYPTO --> RAFT
+    RAFT --> TRANSPORT
+    TRANSPORT <-->|WebRTC<br/>Data Channels| TRANSPORT
+```
+
+## Low-level architecture
+
+### Message flow
+
+```mermaid
+sequenceDiagram
+    participant App as Application
+    participant Mesh as DandelionMesh
+    participant Raft as Raft Leader
+    participant Peers as Other Peers
+
+    Note over App,Peers: Public message
+    App->>Mesh: sendPublic(data)
+    Mesh->>Raft: propose(PublicMessageEntry)
+    Raft->>Peers: AppendEntries (log replication)
+    Peers-->>Raft: success (majority)
+    Raft->>Mesh: committed
+    Mesh->>App: on('message', PublicMessage)
+    Raft->>Peers: leaderCommit updated
+    Note over Peers: Each peer applies & emits 'message'
+
+    Note over App,Peers: Private message
+    App->>Mesh: sendPrivate(recipientId, data)
+    Mesh->>Mesh: encrypt with recipient's RSA public key
+    Mesh->>Raft: propose(EncryptedPrivateMessage)
+    Raft->>Peers: AppendEntries (encrypted payload in log)
+    Peers-->>Raft: success (majority)
+    Note over Peers: Only recipient can decrypt
+```
+
+### Leader election
+
+```mermaid
+stateDiagram-v2
+    [*] --> Follower
+    Follower --> Candidate: election timeout<br/>(no heartbeat received)
+    Candidate --> Leader: received votes<br/>from majority
+    Candidate --> Candidate: election timeout<br/>(split vote)
+    Candidate --> Follower: discovered higher term<br/>or current leader
+    Leader --> Follower: discovered higher term
+    Leader --> Leader: sends heartbeats<br/>to prevent elections
+```
+
+### Key Design Decisions
+
+- **Transport abstraction** — The `Transport` interface decouples the mesh from PeerJS. Any P2P transport (WebSocket, libp2p, etc.) can be plugged in by implementing the interface.
+
+- **Raft consensus** — Full implementation per the [Raft paper](https://raft.github.io/raft.pdf):
+  - Leader election with randomized timeouts (2000–4000ms default)
+  - Log replication with AppendEntries consistency checks
+  - Commitment only for current-term entries (Figure 8 safety)
+  - Dynamic membership updates as peers join/leave
+
+- **Three log backends** — `InMemoryRaftLog` for ephemeral sessions, `LocalStorageRaftLog` for peers that need to survive page refreshes and rejoin, and `SessionStorageRaftLog` for per-tab durability that clears when the tab is closed.
+
+- **Hybrid encryption** — Private messages use RSA-OAEP to wrap a random AES-256-GCM key. Public keys are exchanged as Raft log entries, so every peer receives them through the same ordered replication path. All peers see the encrypted log entry, but only the intended recipient can decrypt it.
+
+- **Ordered delivery via Raft** — All messages (public and encrypted private) go through Raft as log entries. Non-leader peers forward proposals to the leader. Once committed, public messages are delivered to all; encrypted messages are decrypted only by the intended recipient. This guarantees total ordering of all events across the cluster.
+
+## Support & Bug Report
+
+If you find any bugs or have suggestions, please feel free to [open an issue](https://github.com/predatorray/dandelion-mesh/issues/new).
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

package/build/main/crypto/CryptoService.d.ts

@@ -0,0 +1,31 @@
+/**
+ * RSA-OAEP + AES-GCM hybrid encryption service.
+ *
+ * RSA is used to encrypt a random AES session key, and AES-GCM encrypts the
+ * actual payload. This avoids RSA plaintext size limits while providing
+ * authenticated encryption for the message body.
+ */
+export interface CryptoKeyBundle {
+    publicKey: CryptoKey;
+    privateKey: CryptoKey;
+    /** JWK export of the public key, suitable for broadcasting */
+    publicKeyJwk: JsonWebKey;
+}
+export interface EncryptedPayload {
+    /** RSA-encrypted AES key (hex) */
+    encryptedKey: string;
+    /** AES-GCM initialization vector (hex) */
+    iv: string;
+    /** AES-GCM ciphertext (hex) */
+    ciphertext: string;
+}
+/** Generate an RSA-OAEP key pair and export the public key as JWK */
+export declare function generateKeyBundle(modulusLength?: number): Promise<CryptoKeyBundle>;
+/** Import a peer's public key from its JWK representation */
+export declare function importPublicKey(jwk: JsonWebKey): Promise<CryptoKey>;
+/** Encrypt arbitrary data with a recipient's RSA public key (hybrid encryption) */
+export declare function encrypt(plaintext: Uint8Array, recipientPublicKey: CryptoKey): Promise<EncryptedPayload>;
+/** Decrypt a hybrid-encrypted payload with the recipient's RSA private key */
+export declare function decrypt(payload: EncryptedPayload, privateKey: CryptoKey): Promise<Uint8Array>;
+export declare function arrayBufferToHex(buffer: ArrayBuffer): string;
+export declare function hexToArrayBuffer(hex: string): ArrayBuffer;

package/build/main/crypto/CryptoService.js

@@ -0,0 +1,78 @@
+"use strict";
+/**
+ * RSA-OAEP + AES-GCM hybrid encryption service.
+ *
+ * RSA is used to encrypt a random AES session key, and AES-GCM encrypts the
+ * actual payload. This avoids RSA plaintext size limits while providing
+ * authenticated encryption for the message body.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hexToArrayBuffer = exports.arrayBufferToHex = exports.decrypt = exports.encrypt = exports.importPublicKey = exports.generateKeyBundle = void 0;
+const AES_KEY_LENGTH = 256;
+const AES_IV_LENGTH = 12;
+const RSA_HASH = 'SHA-256';
+/** Generate an RSA-OAEP key pair and export the public key as JWK */
+async function generateKeyBundle(modulusLength = 4096) {
+    const keyPair = await crypto.subtle.generateKey({
+        name: 'RSA-OAEP',
+        modulusLength,
+        publicExponent: new Uint8Array([1, 0, 1]),
+        hash: RSA_HASH,
+    }, true, ['encrypt', 'decrypt']);
+    const publicKeyJwk = await crypto.subtle.exportKey('jwk', keyPair.publicKey);
+    return {
+        publicKey: keyPair.publicKey,
+        privateKey: keyPair.privateKey,
+        publicKeyJwk,
+    };
+}
+exports.generateKeyBundle = generateKeyBundle;
+/** Import a peer's public key from its JWK representation */
+async function importPublicKey(jwk) {
+    return crypto.subtle.importKey('jwk', jwk, { name: 'RSA-OAEP', hash: RSA_HASH }, false, ['encrypt']);
+}
+exports.importPublicKey = importPublicKey;
+/** Encrypt arbitrary data with a recipient's RSA public key (hybrid encryption) */
+async function encrypt(plaintext, recipientPublicKey) {
+    // Generate random AES key
+    const aesKey = await crypto.subtle.generateKey({ name: 'AES-GCM', length: AES_KEY_LENGTH }, true, ['encrypt']);
+    // Encrypt the AES key with RSA
+    const rawAesKey = await crypto.subtle.exportKey('raw', aesKey);
+    const encryptedAesKey = await crypto.subtle.encrypt({ name: 'RSA-OAEP' }, recipientPublicKey, rawAesKey);
+    // Encrypt the plaintext with AES-GCM
+    const iv = crypto.getRandomValues(new Uint8Array(AES_IV_LENGTH));
+    const ciphertext = await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, aesKey, plaintext);
+    return {
+        encryptedKey: arrayBufferToHex(encryptedAesKey),
+        iv: arrayBufferToHex(iv.buffer),
+        ciphertext: arrayBufferToHex(ciphertext),
+    };
+}
+exports.encrypt = encrypt;
+/** Decrypt a hybrid-encrypted payload with the recipient's RSA private key */
+async function decrypt(payload, privateKey) {
+    // Decrypt the AES key with RSA
+    const rawAesKey = await crypto.subtle.decrypt({ name: 'RSA-OAEP' }, privateKey, hexToArrayBuffer(payload.encryptedKey));
+    const aesKey = await crypto.subtle.importKey('raw', rawAesKey, { name: 'AES-GCM', length: AES_KEY_LENGTH }, false, ['decrypt']);
+    // Decrypt the ciphertext with AES-GCM
+    const iv = hexToArrayBuffer(payload.iv);
+    const plaintext = await crypto.subtle.decrypt({ name: 'AES-GCM', iv }, aesKey, hexToArrayBuffer(payload.ciphertext));
+    return new Uint8Array(plaintext);
+}
+exports.decrypt = decrypt;
+// --- Hex conversion utilities ---
+function arrayBufferToHex(buffer) {
+    return Array.from(new Uint8Array(buffer))
+        .map((b) => b.toString(16).padStart(2, '0'))
+        .join('');
+}
+exports.arrayBufferToHex = arrayBufferToHex;
+function hexToArrayBuffer(hex) {
+    const bytes = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < hex.length; i += 2) {
+        bytes[i / 2] = parseInt(hex.substring(i, i + 2), 16);
+    }
+    return bytes.buffer;
+}
+exports.hexToArrayBuffer = hexToArrayBuffer;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiQ3J5cHRvU2VydmljZS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uL3NyYy9jcnlwdG8vQ3J5cHRvU2VydmljZS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiO0FBQUE7Ozs7OztHQU1HOzs7QUFFSCxNQUFNLGNBQWMsR0FBRyxHQUFHLENBQUM7QUFDM0IsTUFBTSxhQUFhLEdBQUcsRUFBRSxDQUFDO0FBQ3pCLE1BQU0sUUFBUSxHQUFHLFNBQVMsQ0FBQztBQWtCM0IscUVBQXFFO0FBQzlELEtBQUssVUFBVSxpQkFBaUIsQ0FDckMsYUFBYSxHQUFHLElBQUk7SUFFcEIsTUFBTSxPQUFPLEdBQUcsTUFBTSxNQUFNLENBQUMsTUFBTSxDQUFDLFdBQVcsQ0FDN0M7UUFDRSxJQUFJLEVBQUUsVUFBVTtRQUNoQixhQUFhO1FBQ2IsY0FBYyxFQUFFLElBQUksVUFBVSxDQUFDLENBQUMsQ0FBQyxFQUFFLENBQUMsRUFBRSxDQUFDLENBQUMsQ0FBQztRQUN6QyxJQUFJLEVBQUUsUUFBUTtLQUNmLEVBQ0QsSUFBSSxFQUNKLENBQUMsU0FBUyxFQUFFLFNBQVMsQ0FBQyxDQUN2QixDQUFDO0lBQ0YsTUFBTSxZQUFZLEdBQUcsTUFBTSxNQUFNLENBQUMsTUFBTSxDQUFDLFNBQVMsQ0FBQyxLQUFLLEVBQUUsT0FBTyxDQUFDLFNBQVMsQ0FBQyxDQUFDO0lBQzdFLE9BQU87UUFDTCxTQUFTLEVBQUUsT0FBTyxDQUFDLFNBQVM7UUFDNUIsVUFBVSxFQUFFLE9BQU8sQ0FBQyxVQUFVO1FBQzlCLFlBQVk7S0FDYixDQUFDO0FBQ0osQ0FBQztBQW5CRCw4Q0FtQkM7QUFFRCw2REFBNkQ7QUFDdEQsS0FBSyxVQUFVLGVBQWUsQ0FBQyxHQUFlO0lBQ25ELE9BQU8sTUFBTSxDQUFDLE1BQU0sQ0FBQyxTQUFTLENBQzVCLEtBQUssRUFDTCxHQUFHLEVBQ0gsRUFBRSxJQUFJLEVBQUUsVUFBVSxFQUFFLElBQUksRUFBRSxRQUFRLEVBQUUsRUFDcEMsS0FBSyxF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

package/build/main/index.d.ts

@@ -0,0 +1,11 @@
+export { Transport, TransportEvents, TransportEventName, } from './transport/Transport';
+export { PeerJSTransport, PeerJSTransportOptions, PeerLike, DataConnectionLike, } from './transport/PeerJSTransport';
+export { generateKeyBundle, importPublicKey, encrypt, decrypt, CryptoKeyBundle, EncryptedPayload, } from './crypto/CryptoService';
+export { RaftNode, RaftNodeOptions } from './raft/RaftNode';
+export { RaftRole, LogEntry, RequestVoteArgs, RequestVoteResult, AppendEntriesArgs, AppendEntriesResult, RaftMessage, RaftPersistentState, RaftNodeEvents, } from './raft/types';
+export { RaftLog } from './raft/log/RaftLog';
+export { InMemoryRaftLog } from './raft/log/InMemoryRaftLog';
+export { LocalStorageRaftLog } from './raft/log/LocalStorageRaftLog';
+export { SessionStorageRaftLog } from './raft/log/SessionStorageRaftLog';
+export { DandelionMesh, DandelionMeshOptions } from './mesh/DandelionMesh';
+export { PublicMessage, PrivateMessage, MeshMessage, DandelionMeshEvents, } from './mesh/types';

package/build/main/index.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DandelionMesh = exports.SessionStorageRaftLog = exports.LocalStorageRaftLog = exports.InMemoryRaftLog = exports.RaftNode = exports.decrypt = exports.encrypt = exports.importPublicKey = exports.generateKeyBundle = exports.PeerJSTransport = void 0;
+var PeerJSTransport_1 = require("./transport/PeerJSTransport");
+Object.defineProperty(exports, "PeerJSTransport", { enumerable: true, get: function () { return PeerJSTransport_1.PeerJSTransport; } });
+// Crypto
+var CryptoService_1 = require("./crypto/CryptoService");
+Object.defineProperty(exports, "generateKeyBundle", { enumerable: true, get: function () { return CryptoService_1.generateKeyBundle; } });
+Object.defineProperty(exports, "importPublicKey", { enumerable: true, get: function () { return CryptoService_1.importPublicKey; } });
+Object.defineProperty(exports, "encrypt", { enumerable: true, get: function () { return CryptoService_1.encrypt; } });
+Object.defineProperty(exports, "decrypt", { enumerable: true, get: function () { return CryptoService_1.decrypt; } });
+// Raft consensus
+var RaftNode_1 = require("./raft/RaftNode");
+Object.defineProperty(exports, "RaftNode", { enumerable: true, get: function () { return RaftNode_1.RaftNode; } });
+var InMemoryRaftLog_1 = require("./raft/log/InMemoryRaftLog");
+Object.defineProperty(exports, "InMemoryRaftLog", { enumerable: true, get: function () { return InMemoryRaftLog_1.InMemoryRaftLog; } });
+var LocalStorageRaftLog_1 = require("./raft/log/LocalStorageRaftLog");
+Object.defineProperty(exports, "LocalStorageRaftLog", { enumerable: true, get: function () { return LocalStorageRaftLog_1.LocalStorageRaftLog; } });
+var SessionStorageRaftLog_1 = require("./raft/log/SessionStorageRaftLog");
+Object.defineProperty(exports, "SessionStorageRaftLog", { enumerable: true, get: function () { return SessionStorageRaftLog_1.SessionStorageRaftLog; } });
+// Mesh (main API)
+var DandelionMesh_1 = require("./mesh/DandelionMesh");
+Object.defineProperty(exports, "DandelionMesh", { enumerable: true, get: function () { return DandelionMesh_1.DandelionMesh; } });
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7O0FBTUEsK0RBS3FDO0FBSm5DLGtIQUFBLGVBQWUsT0FBQTtBQU1qQixTQUFTO0FBQ1Qsd0RBT2dDO0FBTjlCLGtIQUFBLGlCQUFpQixPQUFBO0FBQ2pCLGdIQUFBLGVBQWUsT0FBQTtBQUNmLHdHQUFBLE9BQU8sT0FBQTtBQUNQLHdHQUFBLE9BQU8sT0FBQTtBQUtULGlCQUFpQjtBQUNqQiw0Q0FBNEQ7QUFBbkQsb0dBQUEsUUFBUSxPQUFBO0FBYWpCLDhEQUE2RDtBQUFwRCxrSEFBQSxlQUFlLE9BQUE7QUFDeEIsc0VBQXFFO0FBQTVELDBIQUFBLG1CQUFtQixPQUFBO0FBQzVCLDBFQUF5RTtBQUFoRSw4SEFBQSxxQkFBcUIsT0FBQTtBQUU5QixrQkFBa0I7QUFDbEIsc0RBQTJFO0FBQWxFLDhHQUFBLGFBQWEsT0FBQSJ9

package/build/main/mesh/DandelionMesh.d.ts

@@ -0,0 +1,115 @@
+import { CryptoKeyBundle } from '../crypto/CryptoService';
+import { RaftNodeOptions } from '../raft/RaftNode';
+import { RaftLog } from '../raft/log/RaftLog';
+import { Transport } from '../transport/Transport';
+import { DandelionMeshEvents, MeshLogCommand } from './types';
+export interface DandelionMeshOptions {
+    /** RSA modulus length in bits (default 4096) */
+    modulusLength?: number;
+    /** Raft configuration */
+    raft?: RaftNodeOptions;
+    /** Raft log implementation (default: InMemoryRaftLog) */
+    raftLog?: RaftLog<MeshLogCommand>;
+    /** Known peer IDs to connect to on startup */
+    bootstrapPeers?: string[];
+    /**
+     * Pre-generated crypto key bundle. When provided, the mesh skips key
+     * generation and uses these keys directly. Accepts either a resolved
+     * bundle or a Promise (e.g. from a prior `generateKeyBundle()` call).
+     * If omitted, a new key pair is generated automatically.
+     */
+    cryptoKeyBundle?: CryptoKeyBundle | Promise<CryptoKeyBundle>;
+}
+/**
+ * DandelionMesh — a fault-tolerant P2P mesh network for browser applications.
+ *
+ * Combines three layers:
+ * - **Transport** (default: PeerJS) — handles peer-to-peer WebRTC connections.
+ * - **Crypto** — RSA-OAEP + AES-256-GCM hybrid encryption for private messages.
+ * - **Raft consensus** — leader election and totally-ordered log replication.
+ *
+ * All application messages (public broadcasts and encrypted private messages)
+ * flow through the Raft log, guaranteeing every peer sees the same events in
+ * the same order. Non-leader peers forward proposals to the current leader.
+ *
+ * ## Events
+ *
+ * | Event            | Payload                              | When                                       |
+ * |------------------|--------------------------------------|---------------------------------------------|
+ * | `ready`          | `localPeerId: string`                | Transport is open and Raft has started       |
+ * | `message`        | `MeshMessage<T>, replay: boolean`    | A committed log entry is delivered           |
+ * | `peersChanged`   | `peers: string[]`                    | A peer connects or disconnects               |
+ * | `leaderChanged`  | `leaderId: string \| null`           | Raft leader changes                          |
+ * | `error`          | `Error`                              | Transport-level error                        |
+ *
+ * @typeParam T - The application-level payload type for messages.
+ *
+ * @example
+ * ```ts
+ * const transport = new PeerJSTransport({ peerId: 'alice' });
+ * const mesh = new DandelionMesh<GameAction>(transport, {
+ *   bootstrapPeers: ['bob', 'charlie'],
+ * });
+ *
+ * mesh.on('ready', (id) => console.log('My ID:', id));
+ * mesh.on('message', (msg) => {
+ *   if (msg.type === 'public')  console.log(msg.sender, msg.data);
+ *   if (msg.type === 'private') console.log('secret from', msg.sender);
+ * });
+ *
+ * await mesh.sendPublic({ action: 'bet', amount: 100 });
+ * await mesh.sendPrivate('bob', { cards: ['Ah', 'Kd'] });
+ * ```
+ *
+ * @example Providing a pre-generated crypto key bundle
+ * ```ts
+ * const bundle = await generateKeyBundle(2048);
+ * const mesh = new DandelionMesh(transport, { cryptoKeyBundle: bundle });
+ * ```
+ */
+export declare class DandelionMesh<T = unknown> {
+    private readonly transport;
+    private readonly raftLog;
+    private raftNode;
+    private localPeerId;
+    private readonly cryptoReady;
+    private cryptoBundle;
+    private readonly peerPublicKeys;
+    private readonly pendingKeyWaiters;
+    private readonly modulusLength;
+    private readonly raftOptions;
+    private readonly bootstrapPeers;
+    private lastAppliedIndex;
+    private readonly listeners;
+    constructor(transport: Transport, options?: DandelionMeshOptions);
+    /** Send a public (broadcast) message through the Raft cluster */
+    sendPublic(data: T): Promise<boolean>;
+    /** Send an encrypted private message through the Raft cluster */
+    sendPrivate(recipientPeerId: string, data: T): Promise<boolean>;
+    /** Get all connected peer IDs (including self) */
+    get peers(): string[];
+    /** Get the current Raft leader ID */
+    get leaderId(): string | null;
+    /** Whether this node is the Raft leader */
+    get isLeader(): boolean;
+    /** The local peer ID (available after 'ready') */
+    get peerId(): string | undefined;
+    /** Register an event listener */
+    on<E extends keyof DandelionMeshEvents<T>>(event: E, listener: DandelionMeshEvents<T>[E]): void;
+    /** Remove an event listener */
+    off<E extends keyof DandelionMeshEvents<T>>(event: E, listener: DandelionMeshEvents<T>[E]): void;
+    /** Shut down the mesh: stop Raft, close transport */
+    close(): void;
+    private onTransportOpen;
+    private onPeerConnected;
+    private onPeerDisconnected;
+    private onTransportMessage;
+    private onTransportError;
+    private handleControlMessage;
+    private onRaftCommitted;
+    private handleEncryptedCommit;
+    private proposePublicKey;
+    private getOrAwaitPublicKey;
+    private wireMessage;
+    private emit;
+}