bitchat-node 0.1.0

package/src/protocol/binary.ts

@@ -0,0 +1,345 @@
+/**
+ * Binary Protocol Encoder/Decoder
+ * From: bitchat/Protocols/BinaryProtocol.swift
+ *
+ * Wire format:
+ * Header (14 bytes for v1, 16 bytes for v2):
+ * +--------+------+-----+-----------+-------+------------------+
+ * |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*  |
+ * +----------+-------------+---------+------------+
+ */
+
+import {
+  MAX_FRAMED_FILE_BYTES,
+  PADDING_BLOCK_SIZES,
+  RECIPIENT_ID_SIZE,
+  SENDER_ID_SIZE,
+  SIGNATURE_SIZE,
+  V1_HEADER_SIZE,
+  V2_HEADER_SIZE,
+} from './constants.js';
+import { type BitchatPacket, type MessageType, PacketFlags, PeerID } from './types.js';
+
+/**
+ * Calculate optimal padding size for traffic analysis resistance
+ */
+function optimalBlockSize(dataLength: number): number {
+  for (const size of PADDING_BLOCK_SIZES) {
+    if (dataLength <= size - 1) return size;
+  }
+  return Math.ceil((dataLength + 1) / 256) * 256;
+}
+
+/**
+ * PKCS#7 style padding
+ */
+function pad(data: Uint8Array, targetSize: number): Uint8Array {
+  const paddingLength = targetSize - data.length;
+  if (paddingLength <= 0) return data;
+
+  const padded = new Uint8Array(targetSize);
+  padded.set(data);
+  padded.fill(paddingLength, data.length);
+  return padded;
+}
+
+/**
+ * Remove PKCS#7 padding
+ */
+function unpad(data: Uint8Array): Uint8Array {
+  if (data.length === 0) return data;
+
+  const paddingLength = data[data.length - 1];
+  if (paddingLength === 0 || paddingLength > data.length) return data;
+
+  // Verify padding is consistent
+  for (let i = data.length - paddingLength; i < data.length; i++) {
+    if (data[i] !== paddingLength) return data;
+  }
+
+  return data.subarray(0, data.length - paddingLength);
+}
+
+/**
+ * Encode a BitchatPacket to binary wire format
+ */
+export function encode(packet: BitchatPacket, options: { padding?: boolean } = {}): Uint8Array {
+  const { padding = true } = options;
+  const version = packet.version;
+
+  if (version !== 1 && version !== 2) {
+    throw new Error(`Unsupported protocol version: ${version}`);
+  }
+
+  const headerSize = version === 2 ? V2_HEADER_SIZE : V1_HEADER_SIZE;
+
+  // Build flags
+  let flags = 0;
+  if (packet.recipientID && !packet.recipientID.isEmpty) flags |= PacketFlags.HAS_RECIPIENT;
+  if (packet.signature) flags |= PacketFlags.HAS_SIGNATURE;
+  if (packet.route && packet.route.length > 0 && version >= 2) flags |= PacketFlags.HAS_ROUTE;
+  if (packet.isRSR) flags |= PacketFlags.IS_RSR;
+  // TODO: compression flag
+
+  // Calculate sizes
+  const hasRecipient = (flags & PacketFlags.HAS_RECIPIENT) !== 0;
+  const hasSignature = (flags & PacketFlags.HAS_SIGNATURE) !== 0;
+  const hasRoute = (flags & PacketFlags.HAS_ROUTE) !== 0;
+
+  const routeLength = hasRoute ? 1 + (packet.route?.length ?? 0) * SENDER_ID_SIZE : 0;
+  const payloadSize = packet.payload.length;
+
+  // Validate sizes
+  if (version === 1 && payloadSize > 0xffff) {
+    throw new Error('Payload too large for v1 packet');
+  }
+  if (version === 2 && payloadSize > 0xffffffff) {
+    throw new Error('Payload too large for v2 packet');
+  }
+
+  // Calculate total size
+  const totalSize =
+    headerSize +
+    SENDER_ID_SIZE +
+    (hasRecipient ? RECIPIENT_ID_SIZE : 0) +
+    routeLength +
+    payloadSize +
+    (hasSignature ? SIGNATURE_SIZE : 0);
+
+  const buffer = new Uint8Array(totalSize);
+  const view = new DataView(buffer.buffer);
+  let offset = 0;
+
+  // Header
+  buffer[offset++] = version;
+  buffer[offset++] = packet.type;
+  buffer[offset++] = packet.ttl;
+
+  // Timestamp (8 bytes big-endian)
+  view.setBigUint64(offset, packet.timestamp, false);
+  offset += 8;
+
+  // Flags
+  buffer[offset++] = flags;
+
+  // Payload length
+  if (version === 2) {
+    view.setUint32(offset, payloadSize, false);
+    offset += 4;
+  } else {
+    view.setUint16(offset, payloadSize, false);
+    offset += 2;
+  }
+
+  // Sender ID
+  const senderBytes = packet.senderID.toBytes();
+  buffer.set(senderBytes, offset);
+  offset += SENDER_ID_SIZE;
+
+  // Recipient ID (optional)
+  if (hasRecipient && packet.recipientID) {
+    const recipientBytes = packet.recipientID.toBytes();
+    buffer.set(recipientBytes, offset);
+    offset += RECIPIENT_ID_SIZE;
+  }
+
+  // Route (optional, v2+)
+  if (hasRoute && packet.route) {
+    buffer[offset++] = packet.route.length;
+    for (const hop of packet.route) {
+      buffer.set(hop.toBytes(), offset);
+      offset += SENDER_ID_SIZE;
+    }
+  }
+
+  // Payload
+  buffer.set(packet.payload, offset);
+  offset += payloadSize;
+
+  // Signature (optional)
+  if (hasSignature && packet.signature) {
+    buffer.set(packet.signature.subarray(0, SIGNATURE_SIZE), offset);
+    offset += SIGNATURE_SIZE;
+  }
+
+  if (padding) {
+    const targetSize = optimalBlockSize(buffer.length);
+    return pad(buffer, targetSize);
+  }
+
+  return buffer;
+}
+
+/**
+ * Decode binary wire format to BitchatPacket
+ */
+export function decode(data: Uint8Array): BitchatPacket | null {
+  // Try decode as-is first
+  let packet = decodeCore(data);
+  if (packet) return packet;
+
+  // Try after removing padding
+  const unpaddedData = unpad(data);
+  if (unpaddedData.length !== data.length) {
+    packet = decodeCore(unpaddedData);
+  }
+
+  return packet;
+}
+
+function decodeCore(data: Uint8Array): BitchatPacket | null {
+  if (data.length < V1_HEADER_SIZE + SENDER_ID_SIZE) {
+    return null;
+  }
+
+  const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+  let offset = 0;
+
+  const version = data[offset++];
+  if (version !== 1 && version !== 2) return null;
+
+  const headerSize = version === 2 ? V2_HEADER_SIZE : V1_HEADER_SIZE;
+  if (data.length < headerSize + SENDER_ID_SIZE) return null;
+
+  const type = data[offset++] as MessageType;
+  const ttl = data[offset++];
+
+  // Timestamp (8 bytes big-endian)
+  const timestamp = view.getBigUint64(offset, false);
+  offset += 8;
+
+  const flags = data[offset++];
+  const hasRecipient = (flags & PacketFlags.HAS_RECIPIENT) !== 0;
+  const hasSignature = (flags & PacketFlags.HAS_SIGNATURE) !== 0;
+  const isCompressed = (flags & PacketFlags.IS_COMPRESSED) !== 0;
+  const hasRoute = version >= 2 && (flags & PacketFlags.HAS_ROUTE) !== 0;
+  const isRSR = (flags & PacketFlags.IS_RSR) !== 0;
+
+  // Payload length
+  let payloadLength: number;
+  if (version === 2) {
+    payloadLength = view.getUint32(offset, false);
+    offset += 4;
+  } else {
+    payloadLength = view.getUint16(offset, false);
+    offset += 2;
+  }
+
+  // Validate
+  if (payloadLength < 0 || payloadLength > MAX_FRAMED_FILE_BYTES) return null;
+
+  // Sender ID
+  if (offset + SENDER_ID_SIZE > data.length) return null;
+  const senderID = new PeerID(data.subarray(offset, offset + SENDER_ID_SIZE));
+  offset += SENDER_ID_SIZE;
+
+  // Recipient ID
+  let recipientID: PeerID | undefined;
+  if (hasRecipient) {
+    if (offset + RECIPIENT_ID_SIZE > data.length) return null;
+    recipientID = new PeerID(data.subarray(offset, offset + RECIPIENT_ID_SIZE));
+    offset += RECIPIENT_ID_SIZE;
+  }
+
+  // Route
+  let route: PeerID[] | undefined;
+  if (hasRoute) {
+    if (offset >= data.length) return null;
+    const routeCount = data[offset++];
+    if (routeCount > 0) {
+      route = [];
+      for (let i = 0; i < routeCount; i++) {
+        if (offset + SENDER_ID_SIZE > data.length) return null;
+        route.push(new PeerID(data.subarray(offset, offset + SENDER_ID_SIZE)));
+        offset += SENDER_ID_SIZE;
+      }
+    }
+  }
+
+  // Payload
+  if (isCompressed) {
+    // TODO: Handle compression
+    // For now, just read the raw bytes
+    const lengthFieldSize = version === 2 ? 4 : 2;
+    if (payloadLength < lengthFieldSize) return null;
+    // Skip original size field
+    offset += lengthFieldSize;
+    const compressedSize = payloadLength - lengthFieldSize;
+    if (offset + compressedSize > data.length) return null;
+    // Return compressed data as-is for now
+    const payload = new Uint8Array(data.subarray(offset, offset + compressedSize));
+    offset += compressedSize;
+
+    // Signature
+    let signature: Uint8Array | undefined;
+    if (hasSignature) {
+      if (offset + SIGNATURE_SIZE > data.length) return null;
+      signature = new Uint8Array(data.subarray(offset, offset + SIGNATURE_SIZE));
+    }
+
+    return {
+      version,
+      type,
+      ttl,
+      timestamp,
+      senderID,
+      recipientID,
+      payload,
+      signature,
+      route,
+      isRSR,
+    };
+  }
+
+  if (offset + payloadLength > data.length) return null;
+  const payload = new Uint8Array(data.subarray(offset, offset + payloadLength));
+  offset += payloadLength;
+
+  // Signature
+  let signature: Uint8Array | undefined;
+  if (hasSignature) {
+    if (offset + SIGNATURE_SIZE > data.length) return null;
+    signature = new Uint8Array(data.subarray(offset, offset + SIGNATURE_SIZE));
+  }
+
+  return {
+    version,
+    type,
+    ttl,
+    timestamp,
+    senderID,
+    recipientID,
+    payload,
+    signature,
+    route,
+    isRSR,
+  };
+}
+
+/**
+ * Create binary representation for signing (without signature, TTL=0)
+ */
+export function encodeForSigning(packet: BitchatPacket): Uint8Array {
+  const unsigned: BitchatPacket = {
+    ...packet,
+    signature: undefined,
+    ttl: 0,
+    isRSR: false,
+  };
+  // Must use padding: true to match Swift's toBinaryDataForSigning()
+  return encode(unsigned, { padding: true });
+}
+
+/**
+ * Create message deduplication ID
+ */
+export function makeDeduplicationID(packet: BitchatPacket): string {
+  return `${packet.senderID.toHex()}-${packet.timestamp}-${packet.type}`;
+}

package/src/protocol/constants.ts

@@ -0,0 +1,43 @@
+/**
+ * Bitchat Protocol Constants
+ * From: bitchat/Protocols/BitchatProtocol.swift
+ *       bitchat/Services/BLE/BLEService.swift
+ */
+
+// BLE Service and Characteristic UUIDs
+export const SERVICE_UUID = 'f47b5e2d-4a9e-4c5a-9b3f-8e1d2c3a4b5c'; // mainnet
+export const SERVICE_UUID_TESTNET = 'f47b5e2d-4a9e-4c5a-9b3f-8e1d2c3a4b5a';
+export const CHARACTERISTIC_UUID = 'a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d';
+
+// Binary protocol sizes
+export const SENDER_ID_SIZE = 8;
+export const RECIPIENT_ID_SIZE = 8;
+export const SIGNATURE_SIZE = 64;
+export const V1_HEADER_SIZE = 14;
+export const V2_HEADER_SIZE = 16;
+
+// Protocol limits
+export const DEFAULT_TTL = 7;
+export const MAX_TTL = 7;
+export const MAX_MESSAGE_LENGTH = 4096;
+export const MAX_FRAMED_FILE_BYTES = 10 * 1024 * 1024; // 10MB
+export const BLE_DEFAULT_FRAGMENT_SIZE = 182;
+export const BLE_MAX_MTU = 512;
+
+// Padding block sizes for traffic analysis resistance
+export const PADDING_BLOCK_SIZES = [256, 512, 1024, 2048] as const;
+
+// Timing constants (milliseconds)
+export const ANNOUNCE_MIN_INTERVAL_MS = 5000;
+export const MAINTENANCE_INTERVAL_MS = 30000;
+export const CONNECT_RATE_LIMIT_INTERVAL_MS = 1000;
+export const REACHABILITY_RETENTION_VERIFIED_MS = 300000; // 5 min
+export const REACHABILITY_RETENTION_UNVERIFIED_MS = 60000; // 1 min
+
+// Connection limits
+export const MAX_CENTRAL_LINKS = 7;
+export const MAX_IN_FLIGHT_ASSEMBLIES = 10;
+export const HIGH_DEGREE_THRESHOLD = 5;
+
+// Compression threshold
+export const COMPRESSION_THRESHOLD = 256;

package/src/protocol/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Protocol module exports
+ */
+
+export { decode, encode, encodeForSigning, makeDeduplicationID } from './binary.js';
+export * from './constants.js';
+export {
+  type AnnouncementData,
+  decodeAnnouncement,
+  decodePrivateMessage,
+  encodeAnnouncement,
+  encodePrivateMessage,
+  type PrivateMessageData,
+} from './packets.js';
+export * from './types.js';

package/src/protocol/packets.ts

@@ -0,0 +1,223 @@
+/**
+ * Packet Payload Encoders/Decoders
+ * TLV (Type-Length-Value) format for announce and private message payloads
+ * From: bitchat/Protocols/Packets.swift
+ */
+
+// TLV Types for Announcement
+const AnnounceType = {
+  NICKNAME: 0x01,
+  NOISE_PUBLIC_KEY: 0x02,
+  SIGNING_PUBLIC_KEY: 0x03,
+  DIRECT_NEIGHBORS: 0x04,
+} as const;
+
+// TLV Types for Private Message
+const PrivateMessageType = {
+  MESSAGE_ID: 0x00,
+  CONTENT: 0x01,
+} as const;
+
+/**
+ * Announcement payload data
+ */
+export interface AnnouncementData {
+  nickname: string;
+  noisePublicKey?: Uint8Array;
+  signingPublicKey?: Uint8Array;
+  directNeighbors?: Uint8Array[];
+}
+
+/**
+ * Private message payload data
+ */
+export interface PrivateMessageData {
+  messageID: string;
+  content: string;
+}
+
+/**
+ * Encode announcement payload as TLV
+ */
+export function encodeAnnouncement(data: AnnouncementData): Uint8Array {
+  const parts: Uint8Array[] = [];
+
+  // Nickname TLV
+  const nicknameBytes = new TextEncoder().encode(data.nickname);
+  if (nicknameBytes.length > 255) {
+    throw new Error('Nickname too long');
+  }
+  parts.push(new Uint8Array([AnnounceType.NICKNAME, nicknameBytes.length]));
+  parts.push(nicknameBytes);
+
+  // Noise public key TLV
+  if (data.noisePublicKey && data.noisePublicKey.length > 0) {
+    parts.push(new Uint8Array([AnnounceType.NOISE_PUBLIC_KEY, data.noisePublicKey.length]));
+    parts.push(data.noisePublicKey);
+  }
+
+  // Signing public key TLV
+  if (data.signingPublicKey && data.signingPublicKey.length > 0) {
+    parts.push(new Uint8Array([AnnounceType.SIGNING_PUBLIC_KEY, data.signingPublicKey.length]));
+    parts.push(data.signingPublicKey);
+  }
+
+  // Direct neighbors TLV
+  if (data.directNeighbors && data.directNeighbors.length > 0) {
+    const neighborsData = new Uint8Array(data.directNeighbors.length * 8);
+    let offset = 0;
+    for (const neighbor of data.directNeighbors) {
+      neighborsData.set(neighbor.subarray(0, 8), offset);
+      offset += 8;
+    }
+    parts.push(new Uint8Array([AnnounceType.DIRECT_NEIGHBORS, neighborsData.length]));
+    parts.push(neighborsData);
+  }
+
+  // Concatenate all parts
+  const totalLength = parts.reduce((sum, p) => sum + p.length, 0);
+  const result = new Uint8Array(totalLength);
+  let offset = 0;
+  for (const part of parts) {
+    result.set(part, offset);
+    offset += part.length;
+  }
+
+  return result;
+}
+
+/**
+ * Decode announcement payload from TLV
+ */
+export function decodeAnnouncement(data: Uint8Array): AnnouncementData | null {
+  let offset = 0;
+  let nickname: string | undefined;
+  let noisePublicKey: Uint8Array | undefined;
+  let signingPublicKey: Uint8Array | undefined;
+  let directNeighbors: Uint8Array[] | undefined;
+
+  while (offset + 2 <= data.length) {
+    const type = data[offset++];
+    const length = data[offset++];
+
+    if (offset + length > data.length) {
+      return null; // Truncated
+    }
+
+    const value = data.subarray(offset, offset + length);
+    offset += length;
+
+    switch (type) {
+      case AnnounceType.NICKNAME:
+        nickname = new TextDecoder().decode(value);
+        break;
+      case AnnounceType.NOISE_PUBLIC_KEY:
+        noisePublicKey = Uint8Array.from(value);
+        break;
+      case AnnounceType.SIGNING_PUBLIC_KEY:
+        signingPublicKey = Uint8Array.from(value);
+        break;
+      case AnnounceType.DIRECT_NEIGHBORS:
+        directNeighbors = [];
+        for (let i = 0; i + 8 <= value.length; i += 8) {
+          directNeighbors.push(Uint8Array.from(value.subarray(i, i + 8)));
+        }
+        break;
+      // Unknown types are ignored
+    }
+  }
+
+  if (!nickname) {
+    return null; // Nickname is required
+  }
+
+  return {
+    nickname,
+    noisePublicKey,
+    signingPublicKey,
+    directNeighbors,
+  };
+}
+
+/**
+ * Encode private message payload as TLV
+ */
+export function encodePrivateMessage(data: PrivateMessageData): Uint8Array {
+  const parts: Uint8Array[] = [];
+
+  // Message ID TLV
+  const idBytes = new TextEncoder().encode(data.messageID);
+  parts.push(new Uint8Array([PrivateMessageType.MESSAGE_ID, idBytes.length]));
+  parts.push(idBytes);
+
+  // Content TLV
+  const contentBytes = new TextEncoder().encode(data.content);
+  if (contentBytes.length > 65535) {
+    throw new Error('Content too long');
+  }
+  // For content, use 2-byte length since it can be long
+  parts.push(
+    new Uint8Array([
+      PrivateMessageType.CONTENT,
+      (contentBytes.length >> 8) & 0xff,
+      contentBytes.length & 0xff,
+    ])
+  );
+  parts.push(contentBytes);
+
+  // Concatenate
+  const totalLength = parts.reduce((sum, p) => sum + p.length, 0);
+  const result = new Uint8Array(totalLength);
+  let offset = 0;
+  for (const part of parts) {
+    result.set(part, offset);
+    offset += part.length;
+  }
+
+  return result;
+}
+
+/**
+ * Decode private message payload from TLV
+ */
+export function decodePrivateMessage(data: Uint8Array): PrivateMessageData | null {
+  let offset = 0;
+  let messageID: string | undefined;
+  let content: string | undefined;
+
+  while (offset + 2 <= data.length) {
+    const type = data[offset++];
+
+    // Content uses 2-byte length
+    let length: number;
+    if (type === PrivateMessageType.CONTENT) {
+      if (offset + 2 > data.length) return null;
+      length = (data[offset] << 8) | data[offset + 1];
+      offset += 2;
+    } else {
+      length = data[offset++];
+    }
+
+    if (offset + length > data.length) {
+      return null;
+    }
+
+    const value = data.subarray(offset, offset + length);
+    offset += length;
+
+    switch (type) {
+      case PrivateMessageType.MESSAGE_ID:
+        messageID = new TextDecoder().decode(value);
+        break;
+      case PrivateMessageType.CONTENT:
+        content = new TextDecoder().decode(value);
+        break;
+    }
+  }
+
+  if (!messageID || !content) {
+    return null;
+  }
+
+  return { messageID, content };
+}