Metadata-Version: 2.3
Name: ter-chat
Version: 0.1.0
Summary: A cross-platform, zero-knowledge E2EE terminal chat application.
Author: Nilay Dawn
Author-email: Nilay Dawn <nilaydawn@gmail.com>
Requires-Dist: cryptography>=50.0.1
Requires-Dist: pydantic>=2.13.5
Requires-Dist: pydantic-settings>=2.15.0
Requires-Dist: textual>=8.2.8
Requires-Dist: websockets>=17.1
Requires-Python: >=3.12
Description-Content-Type: text/markdown


# 🔒 SecureCLI

### Cross-Platform Zero-Knowledge E2EE Terminal Chat

> A lightweight, zero-knowledge, End-to-End Encrypted (E2EE) terminal chat platform with cryptographically isolated private rooms.

<p align="center">
  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/Python-3.10%2B-blue.svg" alt="Python 3.10+"></a>
  <a href="https://opensource.org/licenses/GPL-3.0"><img src="https://img.shields.io/badge/License-GPLv3-blue.svg" alt="License: GPLv3"></a>
  <a href="https://textual.textualize.io/"><img src="https://img.shields.io/badge/TUI-Textual-teal.svg" alt="TUI: Textual"></a>
  <a href="https://cryptography.io/"><img src="https://img.shields.io/badge/Crypto-X25519%20%2B%20AES--256--GCM-brightgreen.svg" alt="Crypto: X25519 + AES-256-GCM"></a>
</p>


## 📖 Overview

**SecureCLI** brings modern cryptographic privacy directly into the terminal without relying on heavy Electron or web-wrapper clients .

Unlike low-level network utilities such as Cryptcat, which rely on point-to-point raw TCP sockets, manual port forwarding, or pre-shared plaintext passwords, SecureCLI routes traffic through an **asynchronous zero-knowledge WebSocket relay** designed to traverse :

* 🖥️ Windows (PowerShell / Command Prompt)
* 🐧 Linux (Bash / Zsh)
* 🍎 macOS (Terminal / iTerm2)
* 🔥 Corporate firewalls and residential NAT routers
* ☁️ Cloud container hosting platforms (Render, Fly.io, Koyeb)

The relay server **never receives plaintext messages or private keys**. It only forwards base64-encoded ciphertext envelopes and the public keys required to establish peer sessions .

---

### 🔐 Cryptographically Isolated Rooms

Users sharing a common passphrase independently derive :
* A deterministic **Room ID** ($R_{id}$) for zero-knowledge server-side routing .
* A private **Room Key** ($K_{group}$) for authenticated symmetric broadcast encryption .

Because raw passphrases never leave the client device, different groups connected to the exact same relay server cannot discover each other, view membership lists, or inspect outside traffic .

---

## ✨ Features

| Feature | Description |
|---|---|
| 🔒 **Zero-Knowledge Relay** | The relay routes encrypted envelopes without access to plaintext payloads or private keys . |
| 🏠 **Private Rooms** | Deterministic room partitioning and broadcast keys derived locally using HKDF-SHA256 . |
| 🔑 **X25519 E2EE** | Direct 1-on-1 conversations use Elliptic Curve Diffie-Hellman (ECDH) key exchange . |
| 🛡️ **AES-256-GCM** | Authenticated symmetric encryption (AEAD) ensures confidentiality and tamper detection . |
| 📢 **Encrypted Broadcasts** | Room-wide broadcasts are encrypted using the derived symmetric room key ($K_{group}$) . |
| 💻 **Reactive Terminal UI** | Split-pane interactive interface built with [Textual](https://textual.textualize.io/) and Rich . |
| 🌐 **WebSocket Transport** | Standard outbound WebSocket connections (`wss://` / `ws://`) seamlessly bypass NATs and firewalls . |
| 🔄 **Session Key Caching** | Peer symmetric keys are derived once and cached locally for low-latency transmission . |
| 🧪 **Test Suite** | Comprehensive automated test coverage using `pytest` and `pytest-asyncio` . |
| 📦 **Single-Binary Builds** | Can be packaged into standalone executables using PyInstaller . |

---

## 🏗️ Architecture

SecureCLI follows an **asynchronous Client–Server Zero-Knowledge Relay** architecture :

```text
                        ┌──────────────────────────────┐
                        │      ZERO-KNOWLEDGE RELAY    │
                        │                              │
                        │  • Room Isolation Registry   │
                        │  • Public-Key Directory      │
                        │  • Encrypted Envelope Relay  │
                        │                              │
                        │  ❌ No plaintext             │
                        │  ❌ No private keys          │
                        └──────────────┬───────────────┘
                                       │
                             WSS / TLS │ WSS / TLS
                                       │
                  ┌────────────────────┴────────────────────┐
                  │                                         │
         ┌────────▼─────────┐                      ┌────────▼─────────┐
         │    CLIENT A      │                      │     CLIENT B     │
         │     (Alice)      │                      │      (Bob)       │
         │                  │                      │                  │
         │ • X25519 Keys    │                      │ • X25519 Keys    │
         │ • HKDF-SHA256    │                      │ • HKDF-SHA256    │
         │ • AES-256-GCM    │                      │ • AES-256-GCM    │
         │ • Textual TUI    │                      │ • Textual TUI    │
         └────────┬─────────┘                      └────────┬─────────┘
                  │                                         │
                  └───────── End-to-End Encrypted ──────────┘

```

---

## 🔐 Cryptographic Specification

### 1. Room Credential Derivation

On startup, the client derives two independent parameters from the input passphrase:

$$\text{Room ID } (R_{id}) = \text{HKDF-SHA256}(\text{IKM}=\text{passphrase}, \text{salt}=\text{"securecli-room-id-salt"}, \text{info}=\text{"room-id"}, \text{len}=16)$$

$$\text{Room Key } (K_{group}) = \text{HKDF-SHA256}(\text{IKM}=\text{passphrase}, \text{salt}=\text{"securecli-room-key-salt"}, \text{info}=\text{"room-encryption-key"}, \text{len}=32)$$

* $R_{id}$ is sent to the server for room clustering.


* $K_{group}$ remains strictly on client devices to encrypt and decrypt room broadcasts.



---

### 2. 1-on-1 Direct Messaging (ECDH + HKDF + AES-GCM)

1. **Key Generation**: Each client generates an asymmetric X25519 keypair ($d, Q$).


2. **Key Agreement**: Alice fetches Bob's public key $Q_{\text{Bob}}$ and computes the shared secret:



$$S_{AB} = \text{X25519}(d_{\text{Alice}}, Q_{\text{Bob}}) = \text{X25519}(d_{\text{Bob}}, Q_{\text{Alice}})$$



3. **Key Derivation**: The raw secret is stretched into a 256-bit symmetric session key:



$$K_{\text{session}} = \text{HKDF-SHA256}(S_{AB}, \text{salt}=\emptyset, \text{info}=\text{"securecli-session-v1"}, \text{len}=32)$$



4. **Message Encryption**: Payload is encrypted with AES-256-GCM using a 96-bit CSPRNG nonce:



$$\text{Ciphertext}, \text{Tag} = \text{AES-256-GCM}(K_{\text{session}}, \text{Nonce}, \text{Plaintext})$$




---

## 📡 Relay Protocol

```text
Alice                             Relay Server                              Bob
  │                                     │                                    │
  ├─── 1. register (pub_key, R_id) ────>│                                    │
  │                                     │<─── 2. register (pub_key, R_id) ───┤
  │                                     │                                    │
  ├─── 3. get_key ("bob") ─────────────>│                                    │
  │<── 4. key_response (Bob's pub_key) ─┤                                    │
  │                                     │                                    │
  ├─── 5. message (recipient, nonce, ct) ───────────────────────────────────>│
  │                                     │    (Decrypted locally with K_sess) │

```

---

## 🚀 Quickstart & Usage

### Method 1: Instant Launch via `uvx` (Recommended)

Launch the client without cloning or manual environment setup:

```bash
uvx --from git+[https://github.com/](https://github.com/)nilayDawn/ter-chat securecli <username> <room_passphrase>
```

If you do not have `uvx` installed, you can install it via pip:

```bash
pip install uvx
```

or else you can try pipx:

```bash
pipx run --spec git+https://github.com/nilaydawn/ter-chat securecli <username> <room_passphrase>
```

---

### Method 2: Run from Source

#### 1. Clone & Install Dependencies

```bash
git clone [https://github.com/](https://github.com/)nilayDawn/ter-chat.git
cd ter-chat
uv sync

```

#### 2. Run the Client

```bash
# Connects to default configured relay server
uv run python -m ter_chat.tui alice my-team-room

# Connects to a custom or local relay endpoint
uv run python -m ter_chat.tui alice my-team-room ws://127.0.0.1:8765

```

---

### Method 3: Standalone Executable (No Python Required)

Download the pre-compiled binary for your operating system from the **Releases** tab:

**Windows (PowerShell):**

```powershell
.\securecli.exe alice my-team-room

```

**Linux / Ubuntu (Bash):**

```bash
chmod +x ./securecli
./securecli alice my-team-room

```

**macOS (Zsh):**

```bash
chmod +x ./securecli
./securecli alice my-team-room

```

---

## ⌨️ Interface & Controls

| Action | Control |
| --- | --- |
| **Select / Switch Channel** | Click channel in sidebar or use `Up` / `Down` arrow keys + `Enter`<br> |
| **Send Message** | Type directly into the bottom input prompt and press `Enter`<br> |
| **Room Broadcast** | Select `📢 Broadcast` to send an encrypted message to the entire room

 |
| **Direct E2EE Chat** | Select `@<username>` in the sidebar to switch to 1-on-1 encrypted mode

 |
| **Copy Terminal Text** | Hold `Shift` while dragging your mouse, then press `Ctrl + Shift + C` |
| **Exit Application** | Press `Ctrl + C`, `Ctrl + Q`, or type `/quit`<br> |

---

## 🛠️ Self-Hosting the Relay Server

The relay server is zero-knowledge and stateless.

### 1. Local Run

Clone the repository and run the server locally:

```bash
uv run python -m ter_chat.server

```


---

## 🧪 Running Automated Tests

Run the full test suite verifying cryptographic primitives, room partitioning, and client networking:

```bash
uv run pytest -v

```

---

## 📁 Project Structure

```text
.
├── src/
│   └── ter_chat/
│       ├── __init__.py
│       ├── config.py             # Pydantic environment settings
│       ├── crypto_engine.py      # X25519 ECDH, HKDF-SHA256, AES-256-GCM engine
│       ├── server.py             # Multi-tenant Zero-Knowledge Relay Server
│       ├── client_network.py     # Asynchronous WebSocket Client & Key Caching
│       └── tui.py                # Textual Terminal User Interface
├── tests/
│   ├── test_crypto.py            # Crypto unit tests
│   ├── test_server.py            # Room isolation & relay tests
│   └── test_client_network.py    # E2EE client integration tests
├── render.yaml
├── pyproject.toml
└── README.md

```


## ⚠️ Security Notice

SecureCLI is an open-source security application designed for private terminal workflows. While it adheres to modern cryptographic standards (X25519, HKDF-SHA256, AES-256-GCM with CSPRNG nonces), it has not undergone an independent third-party cryptographic audit.

---

## 📄 License

This project is licensed under the [GPLv3 License](https://www.google.com/search?q=LICENSE).

```

```