bitchat-node

Node.js/TypeScript implementation of the Bitchat BLE mesh networking protocol.

🚀 Production Ready — Core functionality complete and tested. Ready for public use and contributions.

Overview

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)

🎯 What Works Right Now

• 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

Installation

npm install bitchat-node

System Requirements

• Node.js 18+
• macOS, Linux, or Windows with BLE support
• For BLE functionality: @abandonware/noble and @abandonware/bleno native 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

Quick Start

Option 1: CLI Tool (Easiest)

# Install globally
npm install -g bitchat-node

# Run with web UI
bitchat --nickname=YourName --port=3939

# Open browser to http://localhost:3939

Option 2: Library Usage

import { 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();

🌟 Demo: iOS + Node.js Mesh

1. Install Bitchat iOS app on iPhone
2. Run bitchat --nickname=MyNode on Mac/Linux
3. Both devices appear in each other's peer lists automatically
4. Send messages bidirectionally through BLE mesh
5. Add more devices to create multi-hop network

Range: ~10-100 meters depending on hardware and environment.

API Reference

BitchatClient

The main client class for interacting with the Bitchat mesh.

Constructor

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) |

Properties

| 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 |

Methods

| 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 |

Events

| 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 |

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                      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        │
└─────────────────────────────────────────────────────────────┘

🔐 Protocol Details

Packet Format

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*  |
+----------+-------------+---------+------------+

Encryption

Direct messages use the Noise XX pattern (Noise_XX_25519_ChaChaPoly_SHA256):

1. Three-way handshake establishes shared secret
2. Messages encrypted with ChaCha20-Poly1305
3. Perfect forward secrecy via session keys

Identity

Each peer has:

• PeerID: First 8 bytes of SHA-256(NoisePublicKey)
• Signing Key: Ed25519 for packet authentication
• Noise Key: X25519 for key agreement

🎮 Web UI Features

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

🗺️ Roadmap

Phase 1: UI Improvements ✨

• [ ] Enhanced debug panel with packet inspector
• [ ] Conversation threading and history
• [ ] Mobile-responsive design improvements

Phase 2: Nostr Integration 🌐

• [ ] Fallback messaging over Nostr relays
• [ ] Location-based chat via geohash
• [ ] Hybrid BLE + internet topology

Phase 3: Media Support 📷

• [ ] Image transfer with chunking protocol
• [ ] Voice notes with compression
• [ ] File transfer up to 1MB

See ROADMAP.md for complete development plan.

🧪 Development

# 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

🔒 Security Considerations

• 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

🤝 Contributing

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

License

Unlicense — Public Domain

Related Projects

• 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!