A modern, full-stack end-to-end encrypted chat application for secure communications
Hush delivers privacy-first messaging with end-to-end encryption, ensuring your conversations remain completely private. Built with modern technologies for seamless performance across all devices.
- When I started this project there were many questions in my head like how to manage socket, authentication, authorization, encryption, database layer, read receipts, file encryption, private chat, group chat, web workers, multipart upload, secure key exchange and many more. Of course there are many tutorials which covers chat application, mostly they does not cover any of the above mentioned, just the basic concepts. So with this repository I tend to share my findings and a decent implementation putting all the pieces together. I hope it guides the future me's :)
- End-to-end encryption - Messages encrypted with AES-GCM, media with AES-CTR
- RSA key exchange - Secure 2048-bit RSA key pairs for initial key establishment
- Zero-knowledge architecture - Server cannot read your messages or access encryption keys
- Secure file sharing - Documents, images, and media encrypted before upload
- Direct messaging - One-on-one conversations
- Group messaging - Secure group chats with multiple participants
- Read status tracking - Know when messages are delivered and read
- Rich media support - Share images, documents, and files securely
- Block users - Control who can contact you
- User profiles - Customizable user information
- Online status - See when contacts are active
- Video conferencing with scalable SFU architecture
- Message reactions and emoji responses
- Message replies and threading
- Message deletion and editing
- Enhanced media preview - In-app image and video preview
-
Client-Side Encryption: All encryption happens in your browser using Web Crypto API
- AES-GCM for message encryption with authenticated encryption
- AES-CTR for media files with stream-based encryption
- RSA-2048 key pairs for secure key exchange protocols
-
Performance Optimizations
- Web Workers: Multipart uploads and chunk processing in background threads
- Smart File Handling: Large files chunked, uploaded, and reassembled efficiently
- Progressive Downloads: Media files downloaded in chunks and merged seamlessly
- Horizontally Scalable: Socket.io servers with Redis pub/sub for multi-instance support
- JWT + RBAC: Role-based access control with secure token management
- Database Optimization: Custom query generation and TypeORM for complex relationships
- Auto-Generated CRUD: CLI tools for rapid API development
- Type Safety: End-to-end TypeScript with custom type definitions
- Background Processing: Web Workers handle heavy crypto operations without blocking UI
- Real-time Everything: Socket.io for instant message delivery and presence updates
For setup and development instructions, see the contribution guide:
- Read: CONTRIBUTING.md — includes end-to-end server and client setup steps
- Issues and PR workflow are also documented there
hush/
├── server/ # Backend API server
│ ├── src/ # Source code
│ ├── @types/ # Global Types
│ ├── cli/ # CLI for generating CRUD & query
│ ├── db/ # Docker compose file for spinning postgres individually
│ ├── docs/ # Documentation
│ ├── local/ # Internationalization
│ ├── queries/ # Complex sql queries (code is auto-generated)
│ ├── migrations/ # Database migrations
│ └── docker-compose.yml
├── clients/
│ └── web/ # Frontend web application
└
npm run dev # Start development server
npm run prod # Start production server
npm run prod:watch # Start production server in watch mode
npm run build # Build for production
npm run cli g:crud <ModuleName(In Pascal Case)> # Generate a new CRUD Module
npm run cli r:crud <ModuleName(In Pascal Case)> # Remove a CRUD Module
npm run cli g:query # Generate code for SQL queries written in queries directorynpm run dev # Start development server
npm run build # Build for production
npm run build:workers # Build the web workers
npm run watch:workers # Build the web workers in watch mode
npm run start # Start production server-
Message Encryption: AES-GCM (Galois/Counter Mode) with authenticated encryption
- 256-bit keys with built-in authentication
- Prevents tampering and ensures message integrity
- Unique nonce for each message
-
Media Encryption: AES-CTR (Counter Mode) for streaming encryption
- Efficient for large files with parallel processing
- Stream cipher perfect for chunked uploads/downloads
- No padding required, works with any file size
- RSA Key Pairs: 2048-bit RSA encryption for initial key establishment
- Secure Storage: Keys stored in browser's IndexedDB with additional encryption layer
- JWT Authentication: Stateless tokens with configurable expiration
- Role-Based Access Control (RBAC): Granular permissions system
- Refresh Token Rotation: Automatic token refresh with security best practices
- Session Management: Secure logout and session invalidation
- Zero-Knowledge: Server never has access to decryption keys or plaintext
- Runtime: Node.js with TypeScript
- Framework: Express.js with custom middleware
- Database: PostgreSQL with TypeORM
- Real-time: Socket.io with Redis pub/sub for horizontal scaling
- Authentication: JWT with RBAC implementation
- File Storage: Local filesystem / AWS S3 with multipart uploads
- Video Infrastructure: SFU (Selective Forwarding Unit) architecture
- Framework: Next.js with TypeScript
- UI Library: React with Tailwind CSS
- State Management: React Context + Custom hooks
- Real-time: Socket.io client with auto-reconnection
- Encryption: Web Crypto API with custom implementations
- File Handling: Web Workers for background processing
- Performance: Chunk-based uploads/downloads with progress tracking
- Containerization: Docker & Docker Compose
- Development: Hot reload, TypeScript, ESLint
- Deployment: Production-ready Docker images
- End-to-end encrypted messaging
- User authentication and profiles
- Direct and group messaging
- File sharing with encryption
- Read status and user blocking
- Database migrations
- Message replies and threading
- Message reactions with emojis
- Message deletion and editing
- Enhanced media preview
- Push notifications
- Video conferencing with SFU
- Voice messages
- Screen sharing
- File collaboration tools
- Mobile applications (iOS/Android)
- Desktop applications (Electron)
- Browser extensions
- API for third-party integrations
We welcome contributions! Please see our Contributing Guide for details.
This project is participating in Hacktoberfest 2025! We welcome contributions from developers of all skill levels.
Good First Issues: Look for issues labeled with good first issue, hacktoberfest, or help wanted.
Contribution Types:
- 🐛 Bug fixes
- ✨ New features
- 📚 Documentation improvements
- 🧪 Test coverage
- 🎨 UI/UX enhancements
- 🔒 Security improvements
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes
- Commit your changes (
git commit -m 'feat: Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
Please read our Code of Conduct before contributing.
This project is licensed under the MIT License - see the LICENSE file for details.
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Security: Security Policy
- Contributing: Contributing Guide
- Code of Conduct: Code of Conduct
- Lead Developer: @aritradevelops
This project is participating in Hacktoberfest 2025! We welcome contributions from developers of all skill levels. Check out our Contributing Guide to get started.
- As only one instance of the server is running I have not implemented any code for synchronizing the server's socket state. by default socket server's are not horizontally scalable. To achieve horizontal scalability please follow this official guide here
🔒 Try Hush Live | 🐛 Report Bug
Made with ❤️ for privacy-conscious users worldwide
Your conversations, truly private.