👻 GhostLink

High-Performance Serverless P2P Messaging

GhostLink is a decentralized chat app. It connects users directly without using central servers. Direct communication reduces latency and improves performance.

---

🗺️ Roadmap & Status

Version	Status	Description
v1.0	Legacy	First release. Plaintext messaging with reliable UDP transport.
v1.1	Stable	Added Security. End-to-End Encryption (E2EE) using X25519 and ChaCha20-Poly1305 encryption.

---

⚙️ Architecture

GhostLink separates the Web Interface from the P2P core. These parts communicate through thread-safe state. Version 1.1 also adds a secure handshake layer before starting a stream.

Communication Flow

Steps:

1. Initialization: The app starts an HTTP web server and a UDP listener.
2. Discovery: The UDP layer uses a STUN server to get the public IP and open a connection.
3. Secure Handshake: Peers exchange public keys over UDP.
4. Transport: A reliable, encrypted stream is created for data transfer.

---

🚀 Features

• End-to-End Encryption: Uses X25519 keys and HKDF for secure communication.
• Forward Secrecy: Creates session keys for each connection.
• Identity Verification: Shows SAS codes so users can verify connections.
• Reliable UDP: Uses KCP for fast, reliable transport.
• NAT Traversal: Connects through networks using STUN.
• Real-Time Updates: Sends live updates to the web UI using SSE.

---

⚙️ Configuration

GhostLink can be configured using a configuration file, command-line arguments, or both. Configuration is applied in the following order of precedence (highest to lowest):

1. Command-line arguments (highest priority)
2. Configuration file (config.toml)
3. Built-in defaults (lowest priority)

Configuration File

# UDP port for client connections (0 = auto-assign)
client_port = 0

# STUN server for NAT traversal
stun_server = "stun.l.google.com:19302"

# STUN verifier for NAT type detection
stun_verifier = "stun4.l.google.com:19302"

# HTTP web server port
web_port = 8080

# Handshake timeout in seconds
handshake_timeout_secs = 30

# NAT keep-alive interval in seconds
punch_hole_secs = 15

# Disconnect timeout in milliseconds
disconnect_timeout_ms = 500

# Encryption mode: "chacha20poly1305" or "aes256gcm"
encryption_mode = "chacha20poly1305"

Command-Line Arguments

You can override any configuration option using command-line arguments:

# Show all available options
cargo run --release -- --help

# Use a custom configuration file
cargo run --release -- --config /path/to/config.toml

# Override specific settings
cargo run --release -- --web-port 9000 --client-port 5000

# Combine config file with overrides
cargo run --release -- --config myconfig.toml --encryption-mode aes256gcm

Available Options

Option	Short	Description	Default
--config	-c	Path to configuration file	config.toml
--client-port	-p	UDP port for client connections (0 = auto)	0
--stun-server	-s	STUN server address	stun.l.google.com:19302
--stun-verifier	-v	STUN verifier address	stun4.l.google.com:19302
--web-port	-w	HTTP web server port	8080
--handshake-timeout-secs	-t	Handshake timeout in seconds	30
--punch-hole-secs	-k	NAT keep-alive interval in seconds	15
--disconnect-timeout-ms	-d	Disconnect timeout in milliseconds	500
--encryption-mode	-e	Encryption mode (chacha20poly1305 or aes256gcm)	chacha20poly1305

---

🛠️ Technology

Component	Technology	Purpose
Runtime	Tokio	Manages I/O and tasks.
Transport	Tokio KCP	Handles reliable UDP communication.
Cryptography	RustCrypto	Provides secure key and encryption functions.
Web Framework	Axum	HTTP REST API and real-time event streaming.
State	Arc/RwLock	Ensures thread-safe state management.
Discovery	STUN	Resolves public IPs and opens connections.

---

🔒 Security

STATUS: Encrypted

GhostLink v1.1 uses encryption to secure data:

• Key Exchange: Uses X25519 elliptic-curve.
• Ciphers: Uses ChaCha20-Poly1305 or AES-256-GCM.
• Verification: Users can check fingerprints to avoid interception.

Private keys are only stored in memory and never sent or saved.

---

📦 Installation

Requirements

Install the latest versions of Rust and Cargo.

Quick Start

1. Clone the repo:

   git clone https://github.com/pushkar-gr/ghostlink.git
   cd ghostlink

2. Build and run:

   cargo run --release

3. Create a connection:
   • Open http://localhost:8080 in your browser.
   • Copy your public IP.
   • Share it with a peer.
   • Set an optional alias.
   • Press Establish Link.
   • Verify the fingerprint matches your peer’s.

---

🤝 Contributing

1. Fork the repository.
2. Create a branch:

   git checkout -b feature/example-feature

3. Make and commit your changes:

   git commit -m "Explain the feature"

4. Push the branch:

   git push origin feature/example-feature

5. Open a Pull Request.

---

📄 License

This project is licensed under the GNU General Public License v3.0. See the LICENSE file for details.

---

Start chatting today! 👻