Update README.md

2025-08-24 19:51:58 +00:00
parent 9bf02ccdf3
commit 72101e82db
1 changed files with 272 additions and 2 deletions
--- a/README.md
+++ b/README.md
@@ -1,3 +1,273 @@
-# bytechat
+# ByteChat

-ByteChat Online Protocol
+> A secure, end-to-end encrypted real-time chat application with ephemeral messaging
+
+## Overview
+
+ByteChat is a privacy-focused chat application that provides end-to-end encryption for secure communication. Built with modern web technologies, it features temporary rooms, encrypted messaging, and automatic message cleanup to ensure privacy and security.
+
+## Security Features
+
+- **End-to-End Encryption**: RSA-OAEP (2048-bit) for key exchange and AES-GCM (256-bit) for message encryption
+- **Client-Side Key Generation**: All encryption keys are generated in the browser using WebCrypto API
+- **Session-Based Encryption**: Unique session keys for each room with automatic key sharing
+- **Message Integrity**: Duplicate message detection and hash verification
+- **Memory Safety**: Automatic cleanup of sensitive data and expired rooms
+- **Rate Limiting**: Built-in message rate limiting and connection management
+- **CSP Protection**: Content Security Policy headers to prevent XSS attacks
+
+## Features
+
+- **Temporary Rooms**: Create secure chat rooms with optional passwords
+- **Real-time Messaging**: Instant message delivery via WebSockets
+- **Ephemeral Storage**: Messages automatically expire and are cleaned up
+- **User Management**: Anonymous users with auto-generated display names
+- **Connection Recovery**: Automatic reconnection with exponential backoff
+- **Message History**: Limited message buffer (512 messages max per room)
+- **Responsive UI**: Clean, modern interface that works on all devices
+
+## Technology Stack
+
+### Backend
+- **Python Flask** - Web framework
+- **Flask-SocketIO** - WebSocket communication
+- **Eventlet** - Async networking library
+
+### Frontend  
+- **Vanilla JavaScript** - Client-side logic
+- **Socket.IO Client** - Real-time communication
+- **Web Crypto API** - Client-side encryption
+- **Modern CSS** - Responsive styling
+
+## Requirements
+
+- Python 3.7+
+- Modern web browser with WebCrypto API support
+- Network connectivity for WebSocket connections
+
+## Installation
+
+1. **Clone the repository:**
+```bash
+git clone https://rattatwinko.servecounterstrike.com/gitea/rattatwinko/bytechat.git
+cd bytechat
+```
+
+2. **Install Python dependencies:**
+```bash
+pip install flask flask-socketio eventlet
+```
+
+3. **Set environment variables (optional):**
+```bash
+export SECRET_KEY="your-secret-key-here"
+```
+
+4. **Run the server:**
+```bash
+python app.py
+```
+
+5. **Open your browser:**
+```
+http://localhost:5000
+```
+
+## Quick Start
+
+### Creating a Room
+1. Leave the room ID field empty and click "Join/Create Room"
+2. A secure room ID will be generated automatically
+3. Share the room ID with others to let them join
+
+### Joining an Existing Room
+1. Enter the room ID in the input field
+2. Enter the password if the room is password-protected
+3. Click "Join/Create Room"
+
+### Secure Messaging
+1. Once connected, wait for the encryption key exchange to complete
+2. Type your message and press Enter or click Send
+3. All messages are automatically encrypted before transmission
+
+## Encryption Flow
+
+### Key Exchange Process
+1. **Client connects** and generates RSA-2048 key pair locally
+2. **First user** in room generates AES-256-GCM session key
+3. **New users** receive encrypted session key via RSA key exchange
+4. **All messages** are encrypted with the shared session key
+
+### Security Guarantees
+- **Server cannot decrypt messages** - No access to private keys or session keys
+- **Perfect forward secrecy** - Session keys are ephemeral and not stored
+- **Message authenticity** - AES-GCM provides both encryption and authentication
+- **Duplicate protection** - Message hashes prevent replay attacks
+
+## Configuration
+
+### Security Limits
+```javascript
+const MAX_MESSAGE_LENGTH = 4000;      // Max characters per message
+const MAX_ROOM_ID_LENGTH = 32;        // Max room ID length  
+const MAX_MESSAGES = 512;             // Messages stored per room
+const MESSAGE_RATE_LIMIT = 1000;      // Milliseconds between messages
+const MAX_RECONNECT_ATTEMPTS = 10;    // Connection retry limit
+```
+
+### Server Configuration
+```python
+MAX_MESSAGES = 512                    # Message buffer size
+MAX_USERS_PER_ROOM = 1000            # Users per room limit
+MAX_ROOMS_PER_IP = 100               # Rooms per IP address
+USER_SESSION_TIMEOUT = 3600          # Session timeout (seconds)
+ROOM_CLEANUP_INTERVAL = 3600         # Cleanup interval (seconds)
+```
+
+## Project Structure
+
+```
+bytechat/
+├── app.py                   # Flask server with SocketIO handlers
+├── static/
+│   ├── js/
+│   │   └── chat.js         # Client-side encryption & chat logic
+│   ├── css/
+│   │   └── style.css       # Modern UI styling
+│   └── favicon.ico
+├── templates/
+│   └── chat.html           # Single-page chat interface
+└── README.md
+```
+
+## Security Architecture
+
+### Client-Side Security
+- **WebCrypto API** for all cryptographic operations
+- **Content Security Policy** prevents code injection
+- **Input validation** and sanitization on all user data
+- **Automatic memory cleanup** of sensitive data
+- **Clickjacking protection** with frame-busting
+
+### Server-Side Security  
+- **Session validation** for all socket events
+- **Message size limits** prevent DoS attacks
+- **Rate limiting** on connections and messages
+- **IP-based restrictions** prevent abuse
+- **Password hashing** with PBKDF2-SHA256
+- **Failed attempt tracking** prevents brute force
+
+## Privacy Features
+
+- **No message persistence** - Messages expire automatically
+- **Anonymous users** - No registration or personal data required
+- **Temporary rooms** - Rooms are cleaned up after inactivity
+- **Client-side encryption** - Server never sees plaintext messages
+- **Memory-safe cleanup** - Sensitive data is cleared from memory
+
+## Development
+
+### Running in Development
+```bash
+python app.py
+```
+Server will run on `http://localhost:5000` with debug mode enabled.
+
+### Testing Encryption
+1. Open multiple browser tabs/windows
+2. Create a room in one tab
+3. Join the same room in other tabs
+4. Verify messages are encrypted in network traffic
+5. Check browser console for encryption status
+
+## Performance
+
+- **Message Buffer**: Limited to 512 messages per room for memory efficiency
+- **Key Exchange**: RSA-2048 provides good balance of security and performance  
+- **Session Keys**: AES-256-GCM for fast symmetric encryption of messages
+- **Connection Management**: Automatic cleanup prevents resource leaks
+- **Rate Limiting**: Prevents spam and resource exhaustion
+
+## API Reference
+
+### Socket Events
+
+#### Client → Server
+- `join_room` - Join or create a chat room
+- `send_message` - Send encrypted message to room
+- `share_session_key` - Share session key with new user
+
+#### Server → Client
+- `user_connected` - User connection confirmation
+- `room_joined` - Room join confirmation with initial data
+- `user_joined` - New user joined the room
+- `new_message` - New encrypted message received
+- `session_key_received` - Encrypted session key from another user
+- `user_left` - User left the room
+
+### HTTP Endpoints
+- `GET /` - Main chat interface
+- `GET /room/<room_id>` - Direct room access
+- `GET /api/room/<room_id>/info` - Room information API
+
+## 🚨 Security Considerations
+
+### What ByteChat Protects Against
+- ✅ Message interception (E2E encryption)
+- ✅ Server-side data breaches (no plaintext storage)
+- ✅ Man-in-the-middle attacks (key verification)  
+- ✅ Message replay attacks (duplicate detection)
+- ✅ Rate limiting and DoS protection
+
+### Limitations
+- ⚠️ No identity verification (anonymous system)
+- ⚠️ No protection against endpoint compromise
+- ⚠️ Temporary message history only
+- ⚠️ Relies on browser security model
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature-name`
+3. Make your changes with proper testing
+4. Ensure all security measures are maintained
+5. Submit a pull request with detailed description
+
+### Security Guidelines
+- Never store private keys or session keys on server
+- Always validate and sanitize user inputs
+- Maintain rate limiting and connection limits
+- Test encryption/decryption thoroughly
+- Follow secure coding practices
+
+## License
+
+This project is open source. Please check the repository for license details.
+
+## Support
+
+For issues, questions, or security concerns:
+- Open an issue on the repository
+- Check existing issues for similar problems
+- For security vulnerabilities, please report privately
+
+## Recent Updates
+
+- **QoL - U3**: Improved scrolling functionality and user experience
+- Enhanced connection stability and automatic reconnection
+- Better error handling and user feedback
+- Performance optimizations for message handling
+
+## Use Cases
+
+- **Private conversations** without permanent storage
+- **Temporary project discussions** with team members
+- **Secure information sharing** for sensitive topics
+- **Anonymous chat rooms** for privacy-focused communities
+- **Development testing** of encrypted communication
+
+---
+
+**⚠️ Security Notice**: While ByteChat provides strong encryption, it's designed for temporary, privacy-focused communication. For highly sensitive or long-term communication needs, consider additional security measures and proper key management systems.
+
+*ByteChat - Secure, temporary, encrypted messaging for the privacy-conscious.*