bitchat-node 0.1.0

package/src/index.ts

@@ -0,0 +1,95 @@
+/**
+ * bitchat-node
+ * Node.js implementation of the Bitchat BLE mesh protocol
+ *
+ * Compatible with Jack Dorsey's Bitchat app.
+ * @see https://github.com/permissionlesstech/bitchat
+ *
+ * @example
+ * ```typescript
+ * import { BitchatClient } from 'bitchat-node';
+ *
+ * const client = new BitchatClient({ nickname: 'my-node' });
+ *
+ * client.on('message', (message) => {
+ *   console.log(`${message.senderNickname}: ${message.content}`);
+ * });
+ *
+ * client.on('peer:connected', (peer) => {
+ *   console.log(`Connected to ${peer.nickname}`);
+ * });
+ *
+ * await client.start();
+ * await client.sendPublicMessage('Hello mesh!');
+ * ```
+ */
+
+// Main client
+export { BitchatClient, type BitchatClientConfig, type BitchatClientEvents } from './client.js';
+// Crypto
+export {
+  // Noise protocol
+  CipherState,
+  fingerprint,
+  formatFingerprint,
+  generateKeyPair,
+  // Signing
+  generateSigningKeyPair,
+  HandshakeState as NoiseHandshakeState,
+  type NoiseKeyPair,
+  type NoiseRole,
+  NoiseSession,
+  type SigningKeyPair,
+  sha256,
+  sign,
+  verify,
+} from './crypto/index.js';
+// Mesh
+export {
+  type DeduplicatorConfig,
+  type Link,
+  MeshRouter,
+  MessageDeduplicator,
+  type RouterConfig,
+} from './mesh/index.js';
+// Protocol
+export {
+  type BitchatPacket,
+  CHARACTERISTIC_UUID,
+  type ChatMessage,
+  DEFAULT_TTL,
+  type DeliveryStatus,
+  decode,
+  // Binary encoding
+  encode,
+  encodeForSigning,
+  HandshakeState,
+  MAX_MESSAGE_LENGTH,
+  MAX_TTL,
+  // Types
+  MessageType,
+  makeDeduplicationID,
+  NoisePayloadType,
+  PacketFlags,
+  PeerID,
+  type PeerInfo,
+  type ReadReceipt,
+  // Constants
+  SERVICE_UUID,
+  SERVICE_UUID_TESTNET,
+} from './protocol/index.js';
+
+// Sessions
+export {
+  SessionManager,
+  type SessionManagerConfig,
+  type SessionManagerEvents,
+} from './session/index.js';
+
+// Transport
+export {
+  BLELink,
+  BLETransport,
+  type BLETransportConfig,
+  type BLETransportEvents,
+} from './transport/index.js';

package/src/mesh/deduplicator.ts

@@ -0,0 +1,129 @@
+/**
+ * Message Deduplicator
+ * Prevents processing the same message multiple times in the mesh
+ * Uses a simple bloom-filter-like approach with time-based expiry
+ */
+
+export interface DeduplicatorConfig {
+  maxSize: number;
+  maxAgeMs: number;
+}
+
+const DEFAULT_CONFIG: DeduplicatorConfig = {
+  maxSize: 10000,
+  maxAgeMs: 5 * 60 * 1000, // 5 minutes
+};
+
+/**
+ * Efficient message deduplication for mesh networks
+ */
+export class MessageDeduplicator {
+  private seen = new Map<string, number>();
+  private readonly config: DeduplicatorConfig;
+  private cleanupTimer?: ReturnType<typeof setInterval>;
+
+  constructor(config: Partial<DeduplicatorConfig> = {}) {
+    this.config = { ...DEFAULT_CONFIG, ...config };
+
+    // Periodic cleanup
+    this.cleanupTimer = setInterval(() => this.cleanup(), 60000);
+  }
+
+  /**
+   * Check if message was seen and mark it as seen
+   * Returns true if this is a NEW message (not seen before)
+   */
+  markSeen(id: string): boolean {
+    const now = Date.now();
+
+    // Check if already seen
+    const existingTimestamp = this.seen.get(id);
+    if (existingTimestamp !== undefined) {
+      // Already seen - check if expired
+      if (now - existingTimestamp > this.config.maxAgeMs) {
+        // Expired, treat as new
+        this.seen.set(id, now);
+        return true;
+      }
+      return false;
+    }
+
+    // New message - add to seen set
+    this.seen.set(id, now);
+
+    // Trim if too large
+    if (this.seen.size > this.config.maxSize) {
+      this.trimOldest();
+    }
+
+    return true;
+  }
+
+  /**
+   * Check if message was seen (without marking)
+   */
+  hasSeen(id: string): boolean {
+    const timestamp = this.seen.get(id);
+    if (timestamp === undefined) return false;
+
+    // Check expiry
+    if (Date.now() - timestamp > this.config.maxAgeMs) {
+      this.seen.delete(id);
+      return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Remove expired entries
+   */
+  private cleanup(): void {
+    const now = Date.now();
+    const maxAge = this.config.maxAgeMs;
+
+    for (const [id, timestamp] of this.seen) {
+      if (now - timestamp > maxAge) {
+        this.seen.delete(id);
+      }
+    }
+  }
+
+  /**
+   * Trim oldest entries when size limit exceeded
+   */
+  private trimOldest(): void {
+    // Convert to array, sort by timestamp, keep newest half
+    const entries = Array.from(this.seen.entries()).sort((a, b) => a[1] - b[1]);
+
+    const toRemove = Math.floor(entries.length / 2);
+    for (let i = 0; i < toRemove; i++) {
+      this.seen.delete(entries[i][0]);
+    }
+  }
+
+  /**
+   * Clear all entries
+   */
+  reset(): void {
+    this.seen.clear();
+  }
+
+  /**
+   * Stop cleanup timer
+   */
+  destroy(): void {
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+      this.cleanupTimer = undefined;
+    }
+    this.seen.clear();
+  }
+
+  /**
+   * Get current size
+   */
+  get size(): number {
+    return this.seen.size;
+  }
+}

package/src/mesh/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Mesh module exports
+ */
+
+export { type DeduplicatorConfig, MessageDeduplicator } from './deduplicator.js';
+export { type Link, MeshRouter, type RouterConfig, type RouterEvents } from './router.js';

package/src/mesh/router.ts

@@ -0,0 +1,258 @@
+/**
+ * Mesh Router
+ * Handles TTL-based message flooding and routing decisions
+ */
+
+import { EventEmitter } from 'node:events';
+import { makeDeduplicationID } from '../protocol/binary.js';
+import { DEFAULT_TTL, MAX_TTL } from '../protocol/constants.js';
+import { type BitchatPacket, MessageType, type PeerID } from '../protocol/types.js';
+import { MessageDeduplicator } from './deduplicator.js';
+
+export interface RouterConfig {
+  maxTTL: number;
+  defaultTTL: number;
+  probabilisticRelay: boolean;
+  relayProbability: number;
+}
+
+const DEFAULT_ROUTER_CONFIG: RouterConfig = {
+  maxTTL: MAX_TTL,
+  defaultTTL: DEFAULT_TTL,
+  probabilisticRelay: false,
+  relayProbability: 0.8,
+};
+
+export interface Link {
+  id: string;
+  send(data: Uint8Array): Promise<void>;
+  peerID?: PeerID;
+}
+
+export interface RouterEvents {
+  packet: (packet: BitchatPacket, fromLink: Link | null) => void;
+  forward: (packet: BitchatPacket, toLinks: Link[]) => void;
+  drop: (packet: BitchatPacket, reason: string) => void;
+}
+
+/**
+ * Mesh message router with TTL-based flooding
+ */
+export class MeshRouter extends EventEmitter {
+  private readonly config: RouterConfig;
+  private readonly deduplicator: MessageDeduplicator;
+  private readonly links = new Map<string, Link>();
+  private myPeerID: PeerID | null = null;
+
+  // Track ingress link for each message to avoid echo
+  private ingressLinks = new Map<string, string>();
+
+  constructor(config: Partial<RouterConfig> = {}) {
+    super();
+    this.config = { ...DEFAULT_ROUTER_CONFIG, ...config };
+    this.deduplicator = new MessageDeduplicator();
+  }
+
+  /**
+   * Set our own peer ID (to avoid processing our own messages)
+   */
+  setMyPeerID(peerID: PeerID): void {
+    this.myPeerID = peerID;
+  }
+
+  /**
+   * Get our own peer ID
+   */
+  getMyPeerID(): PeerID | null {
+    return this.myPeerID;
+  }
+
+  /**
+   * Add a link (connection to another peer)
+   */
+  addLink(link: Link): void {
+    this.links.set(link.id, link);
+  }
+
+  /**
+   * Remove a link
+   */
+  removeLink(linkId: string): void {
+    this.links.delete(linkId);
+    // Clean up any ingress tracking
+    for (const [msgId, ingressLinkId] of this.ingressLinks) {
+      if (ingressLinkId === linkId) {
+        this.ingressLinks.delete(msgId);
+      }
+    }
+  }
+
+  /**
+   * Get all active links
+   */
+  getLinks(): Link[] {
+    return Array.from(this.links.values());
+  }
+
+  /**
+   * Get peer IDs of all connected links
+   */
+  getConnectedPeerIDs(): PeerID[] {
+    return Array.from(this.links.values())
+      .filter((link): link is Link & { peerID: PeerID } => link.peerID !== undefined)
+      .map((link) => link.peerID);
+  }
+
+  /**
+   * Handle an incoming packet
+   */
+  async handlePacket(packet: BitchatPacket, fromLink: Link | null): Promise<boolean> {
+    const dedupID = makeDeduplicationID(packet);
+
+    // Check deduplication
+    if (!this.deduplicator.markSeen(dedupID)) {
+      this.emit('drop', packet, 'duplicate');
+      return false;
+    }
+
+    // Track ingress link
+    if (fromLink) {
+      this.ingressLinks.set(dedupID, fromLink.id);
+    }
+
+    // Validate TTL
+    if (packet.ttl > this.config.maxTTL) {
+      this.emit('drop', packet, 'ttl_exceeded');
+      return false;
+    }
+
+    // Emit packet for processing
+    this.emit('packet', packet, fromLink);
+
+    // Decide whether to forward
+    if (this.shouldForward(packet)) {
+      await this.forward(packet, fromLink?.id);
+    }
+
+    return true;
+  }
+
+  /**
+   * Send a new packet (originated by us)
+   */
+  async sendPacket(packet: BitchatPacket): Promise<void> {
+    const dedupID = makeDeduplicationID(packet);
+
+    // Mark as seen to avoid processing our own relayed copy
+    this.deduplicator.markSeen(dedupID);
+
+    // Broadcast to all links
+    await this.broadcast(packet);
+  }
+
+  /**
+   * Check if packet should be forwarded
+   */
+  private shouldForward(packet: BitchatPacket): boolean {
+    // Don't forward if TTL exhausted
+    if (packet.ttl <= 0) return false;
+
+    // Don't forward certain message types
+    switch (packet.type) {
+      case MessageType.REQUEST_SYNC:
+        // Sync requests are local-only
+        return false;
+      default:
+        break;
+    }
+
+    // Probabilistic relay under high load
+    if (this.config.probabilisticRelay) {
+      if (Math.random() > this.config.relayProbability) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  /**
+   * Forward a packet (decrement TTL, send to other links)
+   */
+  private async forward(packet: BitchatPacket, excludeLinkId?: string): Promise<void> {
+    // Decrement TTL
+    const forwardPacket: BitchatPacket = {
+      ...packet,
+      ttl: packet.ttl - 1,
+    };
+
+    // Get links to forward to (excluding ingress)
+    const dedupID = makeDeduplicationID(packet);
+    const ingressLinkId = excludeLinkId ?? this.ingressLinks.get(dedupID);
+
+    const targetLinks = Array.from(this.links.values()).filter((link) => link.id !== ingressLinkId);
+
+    if (targetLinks.length === 0) return;
+
+    this.emit('forward', forwardPacket, targetLinks);
+
+    // Send to all target links
+    await this.sendToLinks(forwardPacket, targetLinks);
+  }
+
+  /**
+   * Broadcast to all links
+   */
+  private async broadcast(packet: BitchatPacket): Promise<void> {
+    const targetLinks = Array.from(this.links.values());
+    await this.sendToLinks(packet, targetLinks);
+  }
+
+  /**
+   * Send packet to specific links
+   */
+  private async sendToLinks(packet: BitchatPacket, links: Link[]): Promise<void> {
+    const { encode } = await import('../protocol/binary.js');
+    const data = encode(packet);
+
+    const sendPromises = links.map(async (link) => {
+      try {
+        await link.send(data);
+      } catch (error) {
+        // Log error but don't fail the whole broadcast
+        console.error(`Failed to send to link ${link.id}:`, error);
+      }
+    });
+
+    await Promise.allSettled(sendPromises);
+  }
+
+  /**
+   * Send to a specific peer (if we have a direct link)
+   */
+  async sendToPeer(packet: BitchatPacket, peerID: PeerID): Promise<boolean> {
+    // Find link for this peer
+    const link = Array.from(this.links.values()).find((l) => l.peerID?.equals(peerID));
+
+    if (!link) {
+      // No direct link - broadcast and hope for relay
+      await this.sendPacket(packet);
+      return false;
+    }
+
+    const { encode } = await import('../protocol/binary.js');
+    const data = encode(packet);
+    await link.send(data);
+    return true;
+  }
+
+  /**
+   * Clean up
+   */
+  destroy(): void {
+    this.deduplicator.destroy();
+    this.links.clear();
+    this.ingressLinks.clear();
+    this.removeAllListeners();
+  }
+}