bytechat/README.md

ByteChat

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:

git clone https://rattatwinko.servecounterstrike.com/gitea/rattatwinko/bytechat.git
cd bytechat

2. Install Python dependencies:

pip install flask flask-socketio eventlet

3. Set environment variables (optional):

export SECRET_KEY="your-secret-key-here"

4. Run the server:

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

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

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

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.