permissionlesstech/bitchat
1
0
Fork 0
mirror of https://github.com/permissionlesstech/bitchat.git synced 2026-07-25 12:25:19 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add comprehensive AI-friendly documentation across core files (#328)

Browse Source 
- Created AI_CONTEXT.md as central documentation hub for AI assistants
- Added detailed file-level documentation to all major components
- Documented architecture, design decisions, and security considerations
- Added usage examples and integration guidance
- Improved code discoverability with clear component descriptions

Documentation covers:
- BluetoothMeshService: Core networking and mesh protocol
- BitchatProtocol: Application-layer protocol design
- NoiseProtocol: Cryptographic implementation details
- ChatViewModel: Business logic and state management
- IdentityModels: Three-layer identity architecture
- NoiseEncryptionService: High-level encryption API
- SecureIdentityStateManager: Secure persistence layer
- BinaryProtocol: Low-level wire format

This documentation will significantly improve AI understanding of the codebase structure and enable faster, more accurate assistance with development tasks.

Co-authored-by: jack <jackjackbits@users.noreply.github.com>
This commit is contained in:
jack
2025-07-27 10:18:47 +02:00
committed by GitHub
co-authored by jack
parent e282d077a3
commit 4867ddca0d
9 changed files with 979 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AI_CONTEXT.md
+274
View File
@@ -0,0 +1,274 @@
# 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.