Node.js/TypeScript implementation of the Bitchat BLE mesh networking protocol.
🚀 Production Ready — Core functionality complete and tested. Ready for public use and contributions.
Bitchat is a peer-to-peer mesh network that operates over Bluetooth Low Energy (BLE). This library enables Node.js applications to participate as full peers in the Bitchat mesh, supporting:
✅ Public messages — Broadcast to all peers in range (WORKING)
✅ Direct messages — Encrypted point-to-point communication via Noise protocol (WORKING)
✅ Peer discovery — Automatic discovery and connection to nearby peers (WORKING)
✅ Multi-hop routing — Messages relay through intermediate peers (WORKING)
✅ Web UI — Built-in web interface for monitoring and messaging (WORKING)
✅ CLI Tool — Command-line interface for easy deployment (WORKING)
- Full BLE mesh networking between Mac/Linux nodes and iOS Bitchat app
- Automatic peer discovery and connection management
- Encrypted direct messaging using Noise protocol (perfect forward secrecy)
- Web-based chat interface with real-time updates
- Persistent identity management with key storage
- Message routing through multi-hop mesh topology
- TypeScript implementation with full type safety
npm install bitchat-node- Node.js 18+
- macOS, Linux, or Windows with BLE support
- For BLE functionality:
@abandonware/nobleand@abandonware/blenonative dependencies
On macOS, no additional drivers needed. On Linux, you may need to install BlueZ:
sudo apt-get install bluetooth bluez libbluetooth-dev libudev-dev# Install globally
npm install -g bitchat-node
# Run with web UI
bitchat --nickname=YourName --port=3939
# Open browser to http://localhost:3939import { BitchatClient } from 'bitchat-node';
const client = new BitchatClient({
nickname: 'my-node',
});
// Handle incoming messages
client.on('message', (message) => {
console.log(`[${message.nickname}]: ${message.text}`);
});
// Handle peer discovery
client.on('peer:connected', (peer) => {
console.log(`Peer connected: ${peer.nickname} (${peer.peerID})`);
});
// Start the client
await client.start();
// Send a public message
await client.sendPublicMessage('Hello, mesh!');
// Send a direct message to a specific peer
await client.sendDirectMessage(peerID, 'Private hello');
// Stop when done
await client.stop();- Install Bitchat iOS app on iPhone
- Run
bitchat --nickname=MyNodeon Mac/Linux - Both devices appear in each other's peer lists automatically
- Send messages bidirectionally through BLE mesh
- Add more devices to create multi-hop network
Range: ~10-100 meters depending on hardware and environment.
The main client class for interacting with the Bitchat mesh.
new BitchatClient(config: BitchatClientConfig)| Option | Type | Description |
|---|---|---|
nickname |
string |
Display name for this peer (required) |
staticKeyPair |
NoiseKeyPair |
X25519 key pair for Noise encryption (optional, generated if not provided) |
signingKeyPair |
SigningKeyPair |
Ed25519 key pair for packet signing (optional, generated if not provided) |
testnet |
boolean |
Use testnet service UUID (default: false) |
| Property | Type | Description |
|---|---|---|
peerID |
PeerID |
This peer's unique identifier (derived from public key) |
nickname |
string |
This peer's display name |
fingerprint |
string |
Human-readable identity fingerprint |
| Method | Returns | Description |
|---|---|---|
start() |
Promise<void> |
Start BLE transport and begin peer discovery |
stop() |
Promise<void> |
Stop the client and disconnect from all peers |
sendPublicMessage(text) |
Promise<void> |
Send a public message to all peers |
sendDirectMessage(peerID, text) |
Promise<void> |
Send an encrypted message to a specific peer |
getPeers() |
PeerInfo[] |
Get list of known peers |
getConfig() |
BitchatClientConfig |
Get the client configuration |
| Event | Payload | Description |
|---|---|---|
ready |
— | Client is ready to send/receive |
message |
ChatMessage |
Received a chat message |
peer:connected |
PeerInfo |
A new peer connected |
peer:disconnected |
PeerID |
A peer disconnected |
peer:updated |
PeerInfo |
Peer info was updated |
error |
Error, string |
An error occurred |
┌─────────────────────────────────────────────────────────────┐
│ BitchatClient │
│ High-level API for sending/receiving messages │
└──────────────────────────┬──────────────────────────────────┘
│
┌──────────────────────────┴──────────────────────────────────┐
│ SessionManager │
│ Key storage, Noise handshakes, encryption/decryption │
└──────────────────────────┬──────────────────────────────────┘
│
┌──────────────────────────┴──────────────────────────────────┐
│ MeshRouter │
│ TTL-based flooding, deduplication, routing decisions │
└──────────────────────────┬──────────────────────────────────┘
│
┌──────────────────────────┴──────────────────────────────────┐
│ BLETransport │
│ Central + Peripheral roles, characteristic discovery │
└─────────────────────────────────────────────────────────────┘
Binary wire format with header + payload:
Header (14-16 bytes):
+--------+------+-----+-----------+-------+------------------+
|Version | Type | TTL | Timestamp | Flags | PayloadLength |
|1 byte |1 byte|1byte| 8 bytes | 1 byte| 2 or 4 bytes |
+--------+------+-----+-----------+-------+------------------+
Variable sections:
+----------+-------------+---------+------------+
| SenderID | RecipientID | Payload | Signature |
| 8 bytes | 8 bytes* | Variable| 64 bytes* |
+----------+-------------+---------+------------+
Direct messages use the Noise XX pattern (Noise_XX_25519_ChaChaPoly_SHA256):
- Three-way handshake establishes shared secret
- Messages encrypted with ChaCha20-Poly1305
- Perfect forward secrecy via session keys
Each peer has:
- PeerID: First 8 bytes of SHA-256(NoisePublicKey)
- Signing Key: Ed25519 for packet authentication
- Noise Key: X25519 for key agreement
The built-in web interface (http://localhost:3939) provides:
- Live peer discovery with connection status
- Public chat with all mesh participants
- Private messaging with end-to-end encryption
- Debug panel showing raw packet flows
- Identity management with persistent keys
- Network topology visualization
- Enhanced debug panel with packet inspector
- Conversation threading and history
- Mobile-responsive design improvements
- Fallback messaging over Nostr relays
- Location-based chat via geohash
- Hybrid BLE + internet topology
- Image transfer with chunking protocol
- Voice notes with compression
- File transfer up to 1MB
See ROADMAP.md for complete development plan.
# Install dependencies
npm install
# Build TypeScript
npm run build
# Run tests
npm test
# Run tests with coverage
npm run test:coverage
# Start development mode
npm run dev
# Lint and format
npm run check:fix- BLE Range: Messages only propagate within BLE range (~10-100m depending on hardware)
- No Central Server: All communication is peer-to-peer; no data leaves local mesh
- Forward Secrecy: Direct message sessions use ephemeral keys
- Traffic Analysis: Padding applied to resist packet size analysis
- Identity Persistence: Keys stored locally in
~/.bitchat-node/identity.json
This project is ready for contributions! Areas where help is needed:
- Windows BLE support testing and debugging
- Protocol compatibility with other Bitchat implementations
- Performance optimization for large meshes
- UI/UX improvements for web interface
- Documentation and example applications
Unlicense — Public Domain
- OpenClaw Bitchat Plugin — Integrate with OpenClaw AI assistant
- Bitchat iOS — Original iOS implementation
- Noise Protocol — Cryptographic framework for secure communication
🚀 Ready to deploy? Just run bitchat --nickname=YourName and start meshing!