Skip to content

README.md

Latest commit

 

History

History
275 lines (196 loc) · 10 KB

README.md

File metadata and controls

275 lines (196 loc) · 10 KB

🔐 HushNet Backend

Rust License: MIT PostgreSQL

HushNet Backend is a secure backend server for an end-to-end encrypted (E2EE) instant messaging application, built with Rust and Axum. It implements the Signal Protocol (X3DH + Double Ratchet) to provide cryptographically secure communication between users and devices.

📋 Table of Contents

✨ Features

  • 🔒 End-to-End Encryption (E2EE): Signal Protocol implementation (X3DH + Double Ratchet)
  • 🔐 Ed25519 Authentication: Cryptographic signature-based authentication (no JWT)
  • 👥 Multi-Device Support: Full support for multiple devices per user
  • 💬 Instant Messaging: Direct messages and group chats
  • 🔑 Cryptographic Key Management: Identity keys, prekeys, signed prekeys, one-time prekeys
  • ⚡ Real-time Communication: WebSockets for instant notifications
  • 📡 PostgreSQL LISTEN/NOTIFY: Real-time event notifications
  • 🚀 High Performance: Asynchronous backend powered by Tokio
  • 🐳 Docker Ready: Docker configuration for PostgreSQL
  • 🛡️ Anti-Replay Protection: Timestamp-based request validation

🚀 Quick Start

# Clone the repository
git clone https://github.com/HushNet/HushNet-Backend.git
cd HushNet-Backend

# Start PostgreSQL with Docker
docker build -t hushnet-postgres .
docker run -d -p 5432:5432 --name hushnet-db hushnet-postgres

# Configure environment
echo "DATABASE_URL=postgres://postgres:dev@localhost:5432/e2ee" > .env

# Build and run
cargo build --release
cargo run

Server will start at http://127.0.0.1:8080 🎉

📚 Documentation

Comprehensive documentation is organized into the following sections:

Core Documentation

Setup & Deployment

Additional Resources

🏗️ Architecture

HushNet Backend follows a clean, modular architecture:

┌─────────────────────────────────────────────────────────┐
│                    Client Applications                   │
└───────────────────────┬─────────────────────────────────┘
                        │ HTTP/WebSocket
┌───────────────────────▼─────────────────────────────────┐
│                   Axum Web Framework                     │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │
│  │   Routes    │  │ Middlewares │  │ Controllers │    │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘    │
│         │                 │                 │            │
│         └────────┬────────┴────────┬────────┘           │
│                  │                 │                     │
│         ┌────────▼─────────┐  ┌───▼─────────┐          │
│         │    Services      │  │ Repositories │          │
│         └──────────────────┘  └───────┬──────┘          │
└───────────────────────────────────────┼─────────────────┘
                                        │
                    ┌───────────────────▼──────────────────┐
                    │       PostgreSQL Database            │
                    │  (LISTEN/NOTIFY for real-time)       │
                    └──────────────────────────────────────┘

Communication Flow

  1. Authentication: Ed25519 signature verification on each request
  2. Key Exchange: X3DH handshake to establish secure sessions
  3. Messaging: Double Ratchet encryption for each message
  4. Real-time: PostgreSQL NOTIFY → WebSocket → Clients

🛠️ Technology Stack

Core Framework

  • Rust (Edition 2021) - Programming language
  • Axum 0.7 - Async web framework
  • Tokio - Async runtime
  • SQLx 0.8 - PostgreSQL async client

Cryptography

Database

  • PostgreSQL 14+ - Relational database
  • LISTEN/NOTIFY - Real-time notification mechanism

Utilities

  • Serde - JSON serialization/deserialization
  • Tracing - Structured logging
  • Dotenvy - Environment variable management
  • Anyhow - Error handling
  • UUID - Unique identifier generation
  • Chrono - Date and time handling

📋 Prerequisites

  • Rust 1.70+ (Install)
  • PostgreSQL 14+ (Install)
  • Docker (optional, for database)
  • Cargo (included with Rust)

⚙️ Installation

For detailed installation instructions, see the Installation Guide.

Quick Install

# 1. Clone repository
git clone https://github.com/HushNet/HushNet-Backend.git
cd HushNet-Backend

# 2. Install dependencies
cargo build

# 3. Setup database (with Docker)
docker build -t hushnet-postgres .
docker run -d -p 5432:5432 --name hushnet-db hushnet-postgres

# 4. Configure environment
cp .env.example .env
# Edit .env with your configuration

# 5. Run server
cargo run

🔧 Configuration

Environment Variables

Create a .env file in the project root:

# Database
DATABASE_URL=postgres://postgres:dev@localhost:5432/e2ee

# Logging
RUST_LOG=info

For complete configuration options, see the Configuration Guide.

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Quick Start for Contributors

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Make your changes
  4. Run tests (cargo test)
  5. Format code (cargo fmt)
  6. Check lints (cargo clippy)
  7. Commit changes (git commit -m 'Add amazing feature')
  8. Push to branch (git push origin feature/amazing-feature)
  9. Open a Pull Request

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

🙏 Acknowledgments

  • Signal Protocol for cryptographic inspiration
  • Axum for the excellent web framework
  • The Rust community 🦀

📞 Contact

Built with ❤️ and 🦀 Rust

⭐ If you like this project, please give it a star!

Documentation • API Reference • Contributing