DecentChat

Semi-Decentralized Encrypted Terminal Chat

A privacy-first, terminal-based peer-to-peer messenger with end-to-end encryption. DecentChat enables secure, direct communication between users without relying on a central server for message storage or relay.

Overview

DecentChat is a CLI application designed for users who prioritize privacy and security in their communications. Unlike traditional messaging applications that rely on centralized servers to store and relay messages, DecentChat uses a semi-decentralized architecture where the central server (Supabase) is only used for signaling—establishing the initial connection between peers. Once connected, all communication flows directly between users via secure tunnels with application-level encryption.

Why DecentChat?

Traditional Messengers	DecentChat
Messages stored on servers	Messages never touch a server
Trust server with encryption	End-to-end encryption you control
Central point of failure	Direct P2P communication
Account required	No accounts, just cryptographic identity
Metadata collection	Minimal metadata, privacy-first

Features

End-to-End Encryption

DecentChat implements a robust multi-layer encryption system that ensures your communications remain private and secure. The cryptographic architecture combines multiple industry-standard algorithms to provide comprehensive protection for your messages.

X25519 Key Exchange: Secure Diffie-Hellman key exchange for establishing shared secrets between peers. This elliptic curve cryptography provides strong security with relatively small key sizes, making it ideal for terminal applications where efficiency matters.
AES-256-GCM Encryption: Symmetric encryption with authenticated encryption for message confidentiality and integrity. The GCM mode provides both encryption and authentication in a single operation, ensuring that messages cannot be tampered with during transit.
Ed25519 Signing: Every message is digitally signed for authentication and non-repudiation. This ensures that recipients can verify the sender's identity and that the message has not been altered.

Semi-Decentralized Architecture

The architecture of DecentChat represents a thoughtful balance between decentralization and usability. While fully decentralized systems often struggle with peer discovery and NAT traversal, and centralized systems compromise on privacy, DecentChat's semi-decentralized approach offers the best of both worlds.

Signaling Only: Supabase is used exclusively for connection establishment (presence and offer/answer exchange). The signaling server never sees your messages or encryption keys.
No Message Storage: Your messages are never stored on any server. They flow directly between peers through encrypted tunnels, leaving no trace on intermediate infrastructure.
Direct P2P: All communication flows directly between peers via secure tunnels. This eliminates the risk of server-side data breaches affecting your conversations.
Cloudflare Tunnel Integration: Built-in support for Cloudflare tunnels provides robust NAT traversal without exposing your local network, enabling connections even behind restrictive firewalls.

Privacy-First Design

Privacy is not an afterthought in DecentChat—it is the foundational principle that guides every design decision. From key generation to message transmission, every aspect of the application is designed to minimize data exposure and maximize user control.

Local Key Generation: All cryptographic keys are generated and stored locally on your device. Keys are never transmitted to any server, ensuring that only you have access to your private encryption materials.
Private Keys Never Leave Device: Your private keys are never transmitted over the network. Even during the initial connection handshake, only public keys are exchanged.
Trust-on-First-Use (TOFU): Peer verification model that alerts you if a peer's key changes. This provides protection against man-in-the-middle attacks after the first successful connection.
No Account Required: Your identity is derived from your cryptographic keys. No email, phone number, or personal information is needed to use DecentChat.

Terminal-Native Experience

DecentChat is built from the ground up for terminal users who appreciate the efficiency and flexibility of command-line interfaces. The application leverages modern terminal capabilities while maintaining compatibility across platforms.

Clean CLI Interface: Minimal, distraction-free terminal UI built with BubbleTea. The interface is designed to be intuitive while providing all necessary information at a glance.
No Browser Dependencies: Pure terminal application that works over SSH. This makes DecentChat ideal for use on remote servers, embedded systems, or any environment where graphical interfaces are unavailable.
Single Binary: Easy distribution and deployment—just download and run. No complex installation process or dependency management required.
Cross-Platform: Works on Linux, macOS, and Windows. The application handles platform-specific differences transparently, providing a consistent experience across operating systems.

Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                           DecentChat Architecture                        │
└─────────────────────────────────────────────────────────────────────────┘

┌─────────────────┐                              ┌─────────────────┐
│    User A       │                              │    User B       │
│   (Terminal)    │                              │   (Terminal)    │
│                 │                              │                 │
│  ┌───────────┐  │                              │  ┌───────────┐  │
│  │  UI Layer │  │                              │  │  UI Layer │  │
│  │ (BubbleTea)│ │                              │  │ (BubbleTea)│ │
│  └─────┬─────┘  │                              │  └─────┬─────┘  │
│        │        │                              │        │        │
│  ┌─────▼─────┐  │                              │  ┌─────▼─────┐  │
│  │  Network  │  │      Cloudflare Tunnel       │  │  Network  │  │
│  │  Manager  │◄─┼──────────────────────────────┼─►│  Manager  │  │
│  │   (P2P)   │  │      (Encrypted P2P)         │  │   (P2P)   │  │
│  └─────┬─────┘  │                              │  └─────┬─────┘  │
│        │        │                              │        │        │
│  ┌─────▼─────┐  │      Signaling Server        │  ┌─────▼─────┐  │
│  │ Signaling │  │         (Supabase)           │  │ Signaling │  │
│  │  Client   │◄─┼──────────────────────────────┼─►│  Client   │  │
│  └───────────┘  │   Presence & Tunnel Exchange │  └───────────┘  │
└─────────────────┘                              └─────────────────┘

Connection Flow

┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
│  User A  │     │ Signaling│     │ Signaling│     │  User B  │
│          │     │  Server  │     │  Server  │     │          │
└────┬─────┘     └────┬─────┘     └────┬─────┘     └────┬─────┘
     │                │                │                │
     │  Register      │                │                │
     │───────────────►│                │                │
     │                │  Register      │                │
     │                │◄───────────────│◄───────────────│
     │                │                │                │
     │  Get Online    │                │                │
     │───────────────►│                │                │
     │                │  User List     │                │
     │◄───────────────│                │                │
     │                │                │                │
     │  Tunnel URL    │                │                │
     │───────────────►│  Forward URL   │                │
     │                │───────────────►│───────────────►│
     │                │                │                │
     │                │                │                │
     │◄═══════════════╳════════════════╳═══════════════►│
     │         Direct P2P Connection via Tunnel         │
     │           (Encrypted P2P Chat)                   │
     │◄═══════════════╳════════════════╳═══════════════►│

Security

Encryption Layer

All messages are encrypted at the application level, providing double encryption (application layer + transport layer):

1. Key Exchange (X25519)

The X25519 elliptic curve Diffie-Hellman key exchange provides the foundation for secure session establishment. Each user generates an X25519 keypair on first launch, and these keys are used to derive shared secrets for message encryption.

User A                              User B
--------                            --------
X25519_Private_A                    X25519_Private_B
X25519_Public_A  ────────────────►  X25519_Public_A
X25519_Public_B  ◄────────────────  X25519_Public_B

Shared_Secret_A = X25519(X25519_Private_A, X25519_Public_B)
Shared_Secret_B = X25519(X25519_Private_B, X25519_Public_A)
// Shared_Secret_A == Shared_Secret_B

2. Message Encryption (AES-256-GCM)

Once a shared secret is established, all messages are encrypted using AES-256-GCM (Galois/Counter Mode). This authenticated encryption algorithm provides both confidentiality and integrity guarantees in a single operation.

Each message is encrypted with the shared secret derived from X25519
A unique nonce is generated for each message to prevent replay attacks
Authentication tag ensures message integrity and authenticity

3. Message Signing (Ed25519)

In addition to encryption, every message is digitally signed using Ed25519. This provides non-repudiation and allows recipients to verify that messages truly originated from the claimed sender.

Every message is signed with the sender's Ed25519 private key
Recipient verifies the signature before accepting the message
Prevents message forgery and ensures authenticity

Key Storage

~/.decentchat/
├── identity.enc    # Encrypted identity file (X25519 + Ed25519 keys)
├── .key            # Local encryption key for identity file
└── trusted_peers   # Known peer public keys (TOFU database)

The key storage system is designed with multiple layers of protection. Keys are encrypted at rest using a locally-generated key, ensuring that even if an attacker gains access to the filesystem, they cannot decrypt the identity without the local key file.

Keys are encrypted at rest with a locally-generated key
Private keys are never transmitted over the network
Identity can be backed up by copying the .decentchat directory

Trust Model (TOFU)

Trust-on-First-Use (TOFU) is a security model that balances security with usability. It provides protection against man-in-the-middle attacks after the initial connection, while keeping the user experience straightforward.

First Connection: When connecting to a peer for the first time, their public key is stored locally in the trusted_peers database
Subsequent Connections: The peer's key is verified against the stored key to ensure consistency
Key Change Alert: If a peer's key changes, you receive a warning about potential man-in-the-middle attack

Installation

Prerequisites

Before installing DecentChat, ensure you have the following prerequisites in place:

Go 1.21+: Required for building from source. You can download Go from golang.org/dl
Supabase Account: Free tier works perfectly for signaling. Sign up at supabase.com

Option 1: Build from Source

Building from source is the recommended installation method for users who want the most control over their installation:

# Clone the repository
git clone https://github.com/hiwarkhedeprasad/DecentChat-Terminal.git
cd decentchat

# Install dependencies
go mod tidy

# Build the application
go build -o decentchat ./cmd

# Run
./decentchat

Option 2: Quick Setup Script

For a streamlined installation experience, use the included setup script:

# Clone and run setup script
git clone https://github.com/HiwarkhedePrasad/DecentChat-Terminal.git
cd decentchat
chmod +x setup.sh
./setup.sh

The setup script will check for Go installation, verify environment variables, download dependencies, and build the application automatically.

Option 3: Cross-Compile for Different Platforms

DecentChat supports cross-compilation for various platforms. Use these commands to build for specific target platforms:

# Linux (amd64)
GOOS=linux GOARCH=amd64 go build -o decentchat-linux ./cmd

# macOS (amd64 - Intel)
GOOS=darwin GOARCH=amd64 go build -o decentchat-macos ./cmd

# macOS (arm64 - Apple Silicon)
GOOS=darwin GOARCH=arm64 go build -o decentchat-macos-arm64 ./cmd

# Windows
GOOS=windows GOARCH=amd64 go build -o decentchat.exe ./cmd

Option 4: Windows PowerShell Build

For Windows users, a PowerShell build script is provided that automatically embeds credentials:

# Run the build script
.\build.ps1

This script loads environment variables from .env and builds an executable with embedded Supabase credentials.

Quick Start

1. Set Up Supabase

Create a free Supabase project and configure the database schema for signaling:

-- Run this in Supabase SQL Editor
-- See supabase/schema.sql for complete schema

CREATE TABLE users (
    id TEXT PRIMARY KEY,
    public_key TEXT NOT NULL,
    online BOOLEAN DEFAULT false,
    tunnel_url TEXT,
    last_seen TIMESTAMP WITH TIME ZONE
);

CREATE TABLE signals (
    id SERIAL PRIMARY KEY,
    from_user TEXT NOT NULL,
    to_user TEXT NOT NULL,
    type TEXT NOT NULL, -- 'offer' or 'answer'
    sdp TEXT NOT NULL,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

2. Configure Environment

Create a .env file in the project directory with your Supabase credentials:

SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=your-anon-key

You can find these values in your Supabase dashboard under Project Settings → API.

3. Run DecentChat

./decentchat

On first launch, DecentChat will:

Generate your cryptographic keypairs (X25519 + Ed25519)
Store encrypted keys in ~/.decentchat/
Derive your user ID from your public key
Establish a Cloudflare tunnel for P2P connectivity
Register with the signaling server

Usage

Commands

DecentChat provides a simple command interface for all operations. Commands are entered at the prompt and provide intuitive control over the application:

Command	Description	Example
`/list`	Show all online users	`/list`
`/connect <id>`	Initiate connection to a peer	`/connect b7e2c45f`
`/disconnect`	End current connection	`/disconnect`
`/accept`	Accept incoming connection request	`/accept`
`/decline`	Decline incoming connection request	`/decline`
`/status`	Show connection status	`/status`
`/clear`	Clear chat messages from screen	`/clear`
`/help`	Display available commands	`/help`
`/exit`	Quit the application	`/exit`

Example Session

██████╗ ███████╗███████╗ ██████╗ ██████╗ ██████╗ ██████╗ ███╗   ██╗
██╔══██╗██╔════╝██╔════╝██╔════╝██╔═══██╗██╔══██╗██╔══██╗████╗  ██║
██║  ██║█████╗  ███████╗██║     ██║   ██║██║  ██║██║  ██║██╔██╗ ██║
██║  ██║██╔══╝  ╚════██║██║     ██║   ██║██║  ██║██║  ██║██║╚██╗██║
██████╔╝███████╗███████║╚██████╗╚██████╔╝██████╔╝██████╔╝██║ ╚████║
╚═════╝ ╚══════╝╚══════╝ ╚═════╝ ╚═════╝ ╚═════╝ ╚═════╝ ╚═╝  ╚═══╝

Version 0.1.0 - Semi-Decentralized Encrypted Terminal Chat
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

User ID: a94f3d21
Initializing...
Starting Cloudflare secure tunnel...
Local tunnel established: https://example-try-cloudflare.com

[System] Registered with signaling server
[System] Status: Online

> /list
[System] Online users:
  • b7e2c45f
  • d3a9f882
  • e5c1b67a

> /connect b7e2c45f
[System] Connecting to b7e2c45f...
[System] Offer sent. Waiting for peer to answer...
✓ Connected to peer: b7e2c45f
[System] Secure channel established with E2E encryption

[You] Hey! How's it going?
[Peer] Hi! Everything's great. Loving this encrypted chat!
[You] No servers storing our messages. Pretty cool, right?
[Peer] Exactly! True P2P with end-to-end encryption.

> /disconnect
[System] Disconnected from peer

> /exit
[System] Setting offline status...
[System] Goodbye!

Technical Details

Technology Stack

The technology choices in DecentChat reflect a commitment to security, performance, and maintainability:

Component	Technology	Purpose
Language	Go 1.21+	Core application - chosen for its performance, simplicity, and excellent cryptography support
Terminal UI	BubbleTea	Interactive CLI interface - provides a reactive, Elm-inspired architecture for terminal applications
Styling	Lipgloss	Terminal styling - enables rich formatting and layout in terminal applications
Cryptography	golang.org/x/crypto	Encryption primitives - provides well-audited implementations of X25519, Ed25519, and AES-GCM
WebSocket	gorilla/websocket	Real-time communication - enables persistent connections for signaling
Signaling	Supabase	Connection establishment - provides a reliable, scalable backend for peer discovery
NAT Traversal	Cloudflare Tunnel	Network accessibility - bypasses NAT and firewall restrictions

Network Communication

DecentChat uses a hybrid approach to network communication:

Cloudflare Tunnel: Automatically creates a secure tunnel for inbound connections, enabling P2P connectivity even behind NATs and firewalls
WebSocket Protocol: Used for real-time bidirectional communication between peers
HTTP REST API: Used for signaling operations with Supabase

Session Lifecycle

┌─────────────────────────────────────────────────────────────────┐
│                     Session Lifecycle                           │
└─────────────────────────────────────────────────────────────────┘

    ┌──────────┐
    │  Startup │
    └────┬─────┘
         │
         ▼
    ┌──────────┐     ┌──────────────┐     ┌───────────────┐
    │ Register │────►│  Set Online  │────►│ Poll Signals  │
    │   with   │     │    Status    │     │   (offers)    │
    │Signaling │     └──────────────┘     └───────┬───────┘
    └──────────┘                                  │
                                                  ▼
                                           ┌───────────────┐
                                           │    P2P        │
                                           │  Connection   │
                                           │  via Tunnel   │
                                           └───────────────┘
                                                  │
    ┌──────────┐                                  │
    │ Shutdown │◄─────────────────────────────────┘
    └────┬─────┘
         │
         ▼
    ┌──────────────┐     ┌──────────────┐
    │    Clear     │────►│    Exit      │
    │   Signals    │     │              │
    └──────────────┘     └──────────────┘

Build Options

Different build configurations are available for various use cases:

# Debug build (with symbols for debugging)
go build -o decentchat ./cmd

# Release build (optimized, stripped binary)
CGO_ENABLED=0 go build -ldflags="-s -w" -o decentchat ./cmd

# With version info embedded
go build -ldflags="-X main.Version=$(git describe --tags)" -o decentchat ./cmd

Project Structure

The project follows Go conventions for project layout, with a clear separation of concerns:

decentchat/
├── cmd/
│   └── main.go              # Application entry point, banner, initialization
│
├── internal/
│   ├── config/
│   │   └── config.go        # Configuration loading, env variables, .env parsing
│   │
│   ├── crypto/
│   │   └── crypto.go        # X25519, Ed25519, AES-256-GCM operations
│   │
│   ├── identity/
│   │   └── identity.go      # Identity management, key storage, TOFU
│   │
│   ├── network/
│   │   └── manager.go       # Network manager, tunnel management, P2P connections
│   │
│   ├── signaling/
│   │   └── client.go        # Supabase REST API client for signaling
│   │
│   └── ui/
│       └── app.go           # BubbleTea terminal UI, commands, message display
│
├── supabase/
│   └── schema.sql           # Database schema for signaling server
│
├── .env                     # Environment configuration (not in repo)
├── go.mod                   # Go module definition
├── go.sum                   # Dependency checksums
├── setup.sh                 # Quick setup script for Unix-like systems
├── build.ps1                # Build script for Windows PowerShell
└── README.md                # This file

Module Responsibilities

Each module has a clearly defined responsibility, making the codebase maintainable and testable:

Module	Responsibility
`cmd`	Application bootstrap, banner display, graceful shutdown handling
`config`	Environment loading, .env file parsing, configuration defaults
`crypto`	All cryptographic operations (key generation, encryption, signing, verification)
`identity`	User identity management, local key storage, trusted peers database
`network`	Network operations, Cloudflare tunnel management, P2P connection handling
`signaling`	Communication with Supabase for peer discovery and connection establishment
`ui`	Terminal user interface, command processing, message display, user interactions

Roadmap

Current Version (v0.1.0)

The current release provides a solid foundation for secure P2P messaging:

✅ End-to-end encrypted P2P messaging
✅ Cloudflare tunnel integration for NAT traversal
✅ Terminal UI with BubbleTea
✅ Single peer-to-peer connections
✅ Trust-on-first-use (TOFU) security model
✅ Cross-platform support (Linux, macOS, Windows)

Planned Features

Future releases will expand DecentChat's capabilities while maintaining the core focus on privacy and security:

Feature	Status	Description
Group Chat	🔜 Planned	Multi-peer mesh network for group conversations
File Transfer	🔜 Planned	Secure file sharing over encrypted P2P connections
Message History	🔜 Planned	Local encrypted message history with export functionality
Multi-Connection	🔜 Planned	Multiple simultaneous peer connections
Delivery Receipts	🔜 Planned	Message delivery and read confirmations
Offline Queue	🔜 Planned	Store messages for offline peers
Custom TURN Support	🔜 Planned	Support for custom TURN servers in restrictive networks
Voice Messages	📋 Future	Audio message recording and playback
Plugin System	📋 Future	Extensible plugin architecture for custom functionality

Contributing

We welcome contributions from the community! Whether you're fixing bugs, adding features, or improving documentation, your help is appreciated.

Getting Started

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Make your changes
Run tests (go test ./...)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Code Style

To maintain code quality and consistency, please follow these guidelines:

Follow standard Go conventions (gofmt, go vet)
Add comments for exported functions and types
Update documentation for API changes
Add tests for new functionality
Keep the security-first philosophy in mind for all changes

Security Issues

If you discover a security vulnerability, please do not open a public issue. Instead, email security@example.com with details. We take security seriously and will respond promptly to all security reports.

License

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

MIT License

Copyright (c) 2024 DecentChat

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Acknowledgments

DecentChat would not be possible without these excellent open-source projects:

BubbleTea - Terminal UI framework that makes building interactive CLI applications delightful
Lipgloss - Terminal styling library for beautiful, consistent output
Supabase - Open source Firebase alternative that powers our signaling infrastructure
golang.org/x/crypto - Cryptographic primitives that provide the security foundation
Gorilla WebSocket - WebSocket implementation for Go
Cloudflare Tunnel - Enables P2P connectivity behind NATs

DecentChat — Privacy-first terminal messaging.

Made with ❤️ for privacy enthusiasts

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
cmd		cmd
internal		internal
supabase		supabase
.gitignore		.gitignore
README.md		README.md
build.ps1		build.ps1
go.mod		go.mod
go.sum		go.sum
setup.sh		setup.sh
tmp_font.flf		tmp_font.flf

Folders and files

Latest commit

History

Repository files navigation

DecentChat

Table of Contents

Overview

Why DecentChat?

Features

End-to-End Encryption

Semi-Decentralized Architecture

Privacy-First Design

Terminal-Native Experience

Architecture

Connection Flow

Security

Encryption Layer

1. Key Exchange (X25519)

2. Message Encryption (AES-256-GCM)

3. Message Signing (Ed25519)

Key Storage

Trust Model (TOFU)

Installation

Prerequisites

Option 1: Build from Source

Option 2: Quick Setup Script

Option 3: Cross-Compile for Different Platforms

Option 4: Windows PowerShell Build

Quick Start

1. Set Up Supabase

2. Configure Environment

3. Run DecentChat

Usage

Commands

Example Session

Technical Details

Technology Stack

Network Communication

Session Lifecycle

Build Options

Project Structure

Module Responsibilities

Roadmap

Current Version (v0.1.0)

Planned Features

Contributing

Getting Started

Code Style

Security Issues

License

Acknowledgments

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages