bitchat/AI_CONTEXT.md

AI Context for BitChat

This document provides essential context for AI assistants working on the BitChat codebase. Read this first to understand the project's architecture, design decisions, and key concepts.

Project Overview

BitChat is a decentralized, peer-to-peer messaging application that works over Bluetooth mesh networks without requiring internet connectivity, servers, or phone numbers. It's designed for scenarios where traditional communication infrastructure is unavailable or untrusted.

Key Features

• Bluetooth Mesh Networking: Multi-hop message relay over BLE
• Privacy-First Design: No accounts, no persistent identifiers
• End-to-End Encryption: Uses Noise Protocol Framework for private messages
• Store & Forward: Messages cached for offline peers
• IRC-Style Commands: Familiar /msg, /who interface
• Cross-Platform: Native iOS and macOS support

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                        User Interface                             │
│                    (ContentView, ChatViewModel)                   │
└─────────────────────────────────────────────────────────────────┘
                                   │
┌─────────────────────────────────────────────────────────────────┐
│                     Application Services                          │
│  (MessageRetryService, DeliveryTracker, NotificationService)     │
└─────────────────────────────────────────────────────────────────┘
                                   │
┌─────────────────────────────────────────────────────────────────┐
│                       Security Layer                              │
│     (NoiseEncryptionService, SecureIdentityStateManager)         │
└─────────────────────────────────────────────────────────────────┘
                                   │
┌─────────────────────────────────────────────────────────────────┐
│                      Protocol Layer                               │
│        (BitchatProtocol, BinaryProtocol, NoiseProtocol)         │
└─────────────────────────────────────────────────────────────────┘
                                   │
┌─────────────────────────────────────────────────────────────────┐
│                      Transport Layer                              │
│                   (BluetoothMeshService)                          │
└─────────────────────────────────────────────────────────────────┘

Core Components

1. BluetoothMeshService (Transport Layer)

• Location: bitchat/Services/BluetoothMeshService.swift
• Purpose: Manages BLE connections and implements mesh networking
• Key Responsibilities:
  • Peer discovery (scanning and advertising simultaneously)
  • Connection management (acts as both central and peripheral)
  • Message routing and relay
  • Version negotiation with peers
  • Automatic reconnection and topology management

2. BitchatProtocol (Protocol Layer)

• Location: bitchat/Protocols/BitchatProtocol.swift
• Purpose: Defines the application-level messaging protocol
• Key Features:
  • Binary packet format for efficiency
  • Message types: Chat, Announcement, PrivateMessage, etc.
  • TTL-based routing (max 7 hops)
  • Message deduplication via unique IDs
  • Privacy features: padding, timing obfuscation

3. NoiseProtocol Implementation

• Locations:
  • bitchat/Noise/NoiseProtocol.swift - Core protocol implementation
  • bitchat/Noise/NoiseSession.swift - Session management
  • bitchat/Services/NoiseEncryptionService.swift - High-level encryption API
• Purpose: Provides end-to-end encryption for private messages
• Implementation Details:
  • Uses Noise_XX_25519_AESGCM_SHA256 pattern
  • Mutual authentication via static keys
  • Forward secrecy via ephemeral keys
  • Integrated with identity management

4. Identity System

• Location: bitchat/Identity/
• Three-Layer Model:
  1. Ephemeral Identity: Short-lived, rotates frequently
  2. Cryptographic Identity: Long-term Noise static keypair
  3. Social Identity: User-chosen nickname and metadata
• Trust Levels: Untrusted → Verified → Trusted → Blocked

5. ChatViewModel

• Location: bitchat/ViewModels/ChatViewModel.swift
• Purpose: Central state management and business logic
• Responsibilities:
  • Message handling and batching
  • Command processing (/msg, /who, etc.)
  • UI state management
  • Private chat coordination

Key Design Decisions

1. Protocol Design

• Binary Protocol: Chosen for efficiency over BLE's limited bandwidth
• No JSON: Reduces parsing overhead and message size
• Custom Framing: Handles BLE's 512-byte MTU limitations

2. Security Architecture

• Noise Protocol: Industry-standard, well-analyzed framework
• XX Pattern: Provides mutual authentication and forward secrecy
• No Long-Term Identifiers: Enhances privacy and deniability

3. Mesh Networking

• Store & Forward: Essential for intermittent connectivity
• TTL-Based Routing: Prevents infinite loops in mesh
• Bloom Filters: Efficient duplicate detection

4. Privacy Features

• Message Padding: Obscures message length
• Cover Traffic: Optional dummy messages
• Timing Obfuscation: Randomized delays
• Emergency Wipe: Triple-tap to clear all data

Code Organization

Services (/bitchat/Services/)

Application-level services that coordinate between layers:

• BluetoothMeshService: Core networking
• NoiseEncryptionService: Encryption coordination
• MessageRetryService: Reliability layer
• DeliveryTracker: Acknowledgment handling
• NotificationService: System notifications

Protocols (/bitchat/Protocols/)

Protocol definitions and implementations:

• BitchatProtocol: Application protocol
• BinaryProtocol: Low-level encoding
• BinaryEncodingUtils: Helper functions

Noise (/bitchat/Noise/)

Noise Protocol Framework implementation:

• NoiseProtocol: Core cryptographic operations
• NoiseSession: Session state management
• NoiseHandshakeCoordinator: Handshake orchestration
• NoiseSecurityConsiderations: Security validations

Views & ViewModels

MVVM architecture for UI:

• ContentView: Main chat interface
• ChatViewModel: Business logic and state
• Supporting views for settings, identity, etc.

Development Guidelines

1. Security First

• Never log sensitive data (keys, message content)
• Use SecureLogger for security-aware logging
• Validate all inputs from network
• Follow principle of least privilege

2. Performance Considerations

• BLE has limited bandwidth (~20KB/s practical)
• Minimize protocol overhead
• Batch operations where possible
• Use compression for large messages

3. Testing

• Unit tests for protocol logic
• Integration tests for service interactions
• End-to-end tests for user flows
• Mock objects for BLE testing

4. Error Handling

• Graceful degradation for network issues
• Clear error messages for users
• Automatic retry with backoff
• Never expose internal errors

Common Tasks

Adding a New Message Type

1. Define in MessageType enum in BitchatProtocol.swift
2. Implement encoding/decoding logic
3. Add handling in ChatViewModel
4. Update UI if needed
5. Add tests

Implementing a New Command

1. Add to ChatViewModel.processCommand()
2. Define any new message types needed
3. Implement command logic
4. Add autocomplete support
5. Update help text

Debugging Bluetooth Issues

1. Check BluetoothMeshService logs
2. Verify peer states and connections
3. Monitor characteristic updates
4. Use Bluetooth debugging tools

Security Threat Model

Assumptions

• Adversaries can intercept all Bluetooth traffic
• Devices may be compromised
• No trusted infrastructure available

Protections

• End-to-end encryption for private messages
• Message authentication via HMAC
• Forward secrecy via ephemeral keys
• Deniability through lack of signatures

Limitations

• Public messages are unencrypted by design
• Metadata (who talks to whom) partially visible
• Timing attacks possible on mesh network
• No protection against flooding/spam (yet)

Performance Optimizations

Implemented

• LZ4 compression for messages
• Adaptive duty cycling for battery
• Connection caching and reuse
• Bloom filters for deduplication

Future Improvements

• Protocol buffer encoding
• Better mesh routing algorithms
• Predictive pre-connection
• Smarter retransmission

Troubleshooting Guide

Common Issues

1. Peers not discovering: Check Bluetooth permissions, ensure app is in foreground
2. Messages not delivering: Verify mesh connectivity, check TTL values
3. Handshake failures: Ensure identity state is consistent, check key storage
4. Performance issues: Monitor connection count, check for message loops

External Dependencies

Swift Packages

• CryptoKit: Apple's crypto framework
• Network.framework: For future internet support
• No third-party dependencies (by design)

System Requirements

• iOS 14.0+ / macOS 11.0+
• Bluetooth LE hardware
• ~50MB storage for app + data

Future Roadmap

Planned Features

• Internet bridging for hybrid networks
• Group chat with forward secrecy
• Voice messages with Opus codec
• File transfer support

Architecture Evolution

• Plugin system for transports
• Modular protocol stack
• Cross-platform core library
• Federation between networks

---

Quick Start for AI Assistants

1. Understand the layers: Transport → Protocol → Security → Services → UI
2. Follow the data flow: BLE → Binary → Protocol → ViewModel → View
3. Respect security boundaries: Never mix trusted and untrusted data
4. Test thoroughly: This is critical infrastructure for users
5. Ask about design decisions: Many choices have non-obvious reasons

When in doubt, prioritize security and privacy over features. BitChat users depend on this app in situations where traditional communication has failed them.