permissionlesstech/bitchat
1
0
Fork 0
mirror of https://github.com/permissionlesstech/bitchat.git synced 2026-07-25 11:05:19 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
26bcdf72d7b38cf1786185c645210f546a5b342d
bitchat/AI_CONTEXT.md
T
jackGitHubjack
 327fca9cb1 Remove cover traffic functionality (#389) 
- Remove cover traffic variables and timer
- Remove cover traffic methods (startCoverTraffic, scheduleCoverTraffic, sendDummyMessage, generateDummyContent)
- Remove cover traffic initialization in startSession()
- Remove cover traffic check in handleReceivedPacket
- Remove timer invalidation in reset()
- Update README.md and AI_CONTEXT.md to remove cover traffic mentions

Co-authored-by: jack <jackjackbits@users.noreply.github.com>
2025-08-02 11:36:20 +02:00

471 lines
18 KiB
Markdown
Raw Blame History

# 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
- **Nostr Integration**: Seamless fallback for mutual favorites when out of Bluetooth range
- **Hybrid Transport**: Automatic switching between Bluetooth and Nostr
## Architecture Overview
```
┌─────────────────────────────────────────────────────────────────┐
│ User Interface │
│ (ContentView, ChatViewModel) │
└─────────────────────────────────────────────────────────────────┘
│
┌─────────────────────────────────────────────────────────────────┐
│ Application Services │
│ (MessageRetryService, DeliveryTracker, NotificationService) │
└─────────────────────────────────────────────────────────────────┘
│
┌─────────────────────────────────────────────────────────────────┐
│ Message Router │
│ (Transport selection, Favorites integration) │
└─────────────────────────────────────────────────────────────────┘
│ │
┌───────────────────────────────┐ ┌────────────────────────────────┐
│ Security Layer │ │ Nostr Protocol Layer │
│ (NoiseEncryptionService, │ │ (NostrProtocol, NIP-17, │
│ SecureIdentityStateManager) │ │ NostrRelayManager) │
└───────────────────────────────┘ └────────────────────────────────┘
│ │
┌───────────────────────────────┐ ┌────────────────────────────────┐
│ Protocol Layer │ │ Transport │
│ (BitchatProtocol, Binary- │ │ (WebSocket to Nostr │
│ Protocol, NoiseProtocol) │ │ relay servers) │
└───────────────────────────────┘ └────────────────────────────────┘
│
┌─────────────────────────────────────────────────────────────────┐
│ Bluetooth 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
### 6. Nostr Integration
- **Locations**:
- `bitchat/Nostr/NostrProtocol.swift` - NIP-17 private message implementation
- `bitchat/Nostr/NostrRelayManager.swift` - WebSocket relay connections
- `bitchat/Nostr/NostrIdentity.swift` - Nostr key management
- `bitchat/Services/MessageRouter.swift` - Transport selection logic
- **Purpose**: Enables communication with mutual favorites when out of Bluetooth range
- **Key Features**:
- NIP-17 gift-wrapped private messages for metadata privacy
- Automatic relay connection management
- Seamless transport switching between Bluetooth and Nostr
- Integrated with favorites system for mutual authentication
### 7. MessageRouter
- **Location**: `bitchat/Services/MessageRouter.swift`
- **Purpose**: Intelligent routing between Bluetooth mesh and Nostr transports
- **Transport Selection Logic**:
1. Always prefer Bluetooth mesh when peer is connected
2. Use Nostr for mutual favorites when peer is offline
3. Fail gracefully when no transport is available
- **Message Types Routed**:
- Regular chat messages
- Favorite/unfavorite notifications
- Delivery acknowledgments
- Read receipts
## 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
- **Timing Obfuscation**: Randomized delays
- **Emergency Wipe**: Triple-tap to clear all data
### 5. Nostr Integration
- **NIP-17 Gift Wraps**: Maximum metadata privacy
- **Ephemeral Keys**: Each message uses unique ephemeral keys
- **Mutual Favorites Only**: Requires bidirectional trust
- **Transport Abstraction**: Users don't need to know about Nostr
## 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.
## Nostr Protocol Implementation
### Overview
BitChat integrates Nostr as a secondary transport for communicating with mutual favorites when Bluetooth connectivity is unavailable. This integration is transparent to users - messages automatically route through Nostr when needed.
### NIP-17 Private Direct Messages
BitChat implements NIP-17 (Private Direct Messages) for metadata-private communication:
1. **Gift Wrap Structure**:
```
Gift Wrap (kind 1059) → Seal (kind 13) → Rumor (kind 1)
```
- **Rumor**: The actual message content (unsigned)
- **Seal**: Encrypted rumor, hides sender identity
- **Gift Wrap**: Double-encrypted, tagged for recipient
2. **Ephemeral Keys**:
- Each message uses TWO ephemeral key pairs
- Seal uses one ephemeral key
- Gift wrap uses a different ephemeral key
- Provides sender anonymity and forward secrecy
3. **Timestamp Randomization**:
- ±1 minute randomization (reduced from NIP-17's ±15 minutes)
- Prevents timing correlation attacks
- Configurable in `NostrProtocol.randomizedTimestamp()`
### Favorites Integration
The Nostr transport is only available for mutual favorites:
1. **Favorite Establishment**:
- User favorites a peer via `/fav` command
- Favorite notification sent via Bluetooth (if connected)
- Peer's Nostr public key exchanged during favorite process
- Stored in `FavoritesPersistenceService`
2. **Mutual Requirement**:
- Both peers must favorite each other
- Prevents spam and unwanted Nostr messages
- Enforced by `MessageRouter` transport selection
3. **Nostr Key Management**:
- Derived from Noise static key using BIP-32
- Path: `m/44'/1237'/0'/0/0` (1237 = "NOSTR" in decimal)
- Consistent npub across app reinstalls
- Keys never leave the device
### Message Routing Logic
`MessageRouter` automatically selects transport:
```swift
if peerAvailableOnMesh {
transport = .bluetoothMesh // Always prefer mesh
} else if isMutualFavorite {
transport = .nostr // Use Nostr for offline favorites
} else {
throw MessageRouterError.peerNotReachable
}
```
### Relay Configuration
Default relays (hardcoded for reliability):
- `wss://relay.damus.io`
- `wss://relay.primal.net`
- `wss://offchain.pub`
- `wss://nostr21.com`
Relay selection criteria:
- Geographic distribution
- High uptime
- No authentication required
- Support for ephemeral events
### Message Format
Structured content for different message types:
- Chat: `MSG:<messageID>:<content>`
- Favorite: `FAVORITED:<senderNpub>` or `UNFAVORITED:<senderNpub>`
- Delivery ACK: `DELIVERED:<messageID>`
- Read Receipt: `READ:<base64EncodedReceipt>`
### Implementation Details
1. **NostrRelayManager**:
- Manages WebSocket connections to relays
- Handles reconnection logic
- Processes EVENT, EOSE, OK, NOTICE messages
- Implements NIP-01 relay protocol
2. **NostrProtocol**:
- Implements NIP-17 encryption/decryption
- Handles gift wrap creation/unwrapping
- Manages ephemeral key generation
- Provides Schnorr signatures
3. **ProcessedMessagesService**:
- Prevents duplicate message processing
- Tracks last subscription timestamp
- Persists across app launches
- 30-day retention window
### Security Considerations
1. **Metadata Protection**:
- Sender identity hidden via ephemeral keys
- Recipient only visible in gift wrap p-tag
- Timing correlation prevented via randomization
- Message content double-encrypted
2. **Relay Trust**:
- Relays cannot read message content
- Relays can see recipient pubkey (gift wrap)
- Relays cannot determine sender
- Multiple relays used for redundancy
3. **Key Hygiene**:
- Ephemeral keys used once and discarded
- Static Nostr key derived from Noise key
- No key reuse between messages
- Keys cleared from memory after use
### Debugging Nostr Issues
1. **Check relay connections**:
- Look for "Connected to Nostr relay" in logs
- Verify WebSocket state in NostrRelayManager
- Check for relay errors/notices
2. **Verify gift wrap creation**:
- Enable debug logging in NostrProtocol
- Check ephemeral key generation
- Verify encryption steps
3. **Message delivery**:
- Check ProcessedMessagesService for duplicates
- Verify subscription filters
- Look for EVENT messages in relay responses
## 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
### Working with Nostr Transport
1. Verify mutual favorite status in `FavoritesPersistenceService`
2. Check Nostr key derivation in `NostrIdentity`
3. Monitor relay connections in `NostrRelayManager`
4. Test gift wrap encryption/decryption
5. Verify transport selection in `MessageRouter`
### Adding Nostr Features
1. Understand NIP-17 gift wrap structure
2. Maintain ephemeral key hygiene
3. Test with multiple relays
4. Preserve metadata privacy
5. Handle relay disconnections gracefully
## 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/Nostr → Binary/JSON → 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
6. **Dual Transport**: Remember that messages can flow over Bluetooth OR Nostr
7. **Favorites System**: Nostr only works between mutual favorites
When in doubt, prioritize security and privacy over features. BitChat users depend on this app in situations where traditional communication has failed them.
Reference in New Issue View Git Blame Copy Permalink