# ๐Ÿ” k4li-chat-cli A secure, end-to-end encrypted command-line chat client built on top of [ntfy](https://ntfy.sh) with real-time messaging ECDH-based encryption DM support and zero server trust. --- ## โœจ Features - ๐Ÿ” **End-to-End Encryption (E2EE)** using AES-256 + ECDH key exchange - ๐Ÿ“ก **Real-time messaging** via ntfy's public or self-hosted server - ๐Ÿงฉ **Cross-platform** and terminal-friendly - ๐ŸŒ **Server-agnostic** โ€” the server never sees plaintext messages - ๐Ÿง‘โ€๐Ÿคโ€๐Ÿง‘ **Public room chat + private DMs** - ๐Ÿ•ต๏ธ **Anonymous** โ€” no accounts, emails, or logins - โœจ **Typing indicators**, colored usernames, join/leave notifications - โœ… **Simple CLI commands** like `/msg`, `/who`, `/refresh`, `/help` --- # ๐Ÿ“ Secure File Sharing in `k4li-chat-cli` `k4li-chat-cli` extended to support **encrypted file sharing** while preserving end-to-end encryption. --- ## ๐Ÿ” How it Works The system uses `ntfy`'s built-in support for attachments combined with symmetric AES encryption between peers. 1. The file is encrypted with a shared key. 2. The encrypted file is uploaded as an ntfy attachment. 3. A message is sent with the download URL (optionally encrypted). 4. Peers can download and decrypt the file locally. --- ## ๐Ÿ›  CLI Usage Example ### Sending a File ``` /sendfile path/to/document.pdf ``` - Encrypts the file with AES (shared secret with peer) - Uploads to ntfy - Sends a secure message with a download link ### Receiving and Decrypting - Downloads the encrypted file - Decrypts it using the shared AES key - Saves it as the original filename --- ## ๐Ÿ”’ Security Notes - Files are encrypted **client-side** using the same AES-256 key used for messages. - The ntfy server only stores **ciphertext**, with no knowledge of the contents. - Metadata (like the original filename) is encrypted as well. --- ## โœ… Ideal For - Sharing notes, photos, PDFs between trusted peers - Secure collaboration while traveling or on untrusted networks - Anonymous dropboxes (when combined with anonymous usernames) ### ๐Ÿ‘ป Username Metadata Obfuscation - Usernames are no not visible in message metadata for passive observers (like browsers or sysadmins). - All user-related data (name, message, intent) is embedded in the encrypted message body. --- # ๐Ÿ›ก๏ธ Use Cases for k4li-chat-cli `k4li-chat-cli` is more than a simple command-line chat โ€” it's a privacy-first tool designed for real-world scenarios where mainstream messaging fails or can't be trusted. --- ## ๐ŸŒ When to Use ### ๐Ÿ”“ On Untrusted Networks Whether you're in a public coffee shop, a hotel, or a remote co-working space, `k4li-chat-cli` encrypts messages end-to-end using ECDH and AES-256, meaning **no one โ€” not even the server โ€” can read your messages**. **Perfect for:** - Traveling developers and digital nomads - Hackerspaces and CTFs - Public Wi-Fi use --- ### ๐Ÿ•ต๏ธ When You Can't Use Your Default Messenger Sometimes your default apps aren't accessible โ€” due to firewalls, platform restrictions, or simply unavailability. **Ideal for:** - Censorship circumvention - Messaging without an account - Quick communications without app installs --- ### ๐Ÿ‘ฅ When Interlocutors Use Different Platforms You use Signal, they use Telegram. You prefer Matrix, they only use WhatsApp. Skip the compatibility drama. `k4li-chat-cli` works for everyone with: - A terminal - Internet access **No accounts, no installs, no gatekeeping.** --- ## โœ๏ธ For Journalists, Activists & Whistleblowers - **Anonymous, encrypted by design** - **Peer discovery via public or private ntfy servers** - **Nothing stored on disk or visible in chat history** - **Command-line interface leaves minimal forensic footprint** --- ## ๐Ÿง‘โ€๐Ÿ’ป For Developers - Integrate into scripting workflows - Use in automation - Perfect for ad-hoc coordination across secure tunnels (like Tailscale, VPNs, Tor) --- ## ๐Ÿš€ TL;DR `k4li-chat-cli` is the secure, disposable, encrypted chat tool you've always needed โ€” for when security, interoperability, and simplicity matter most. > No logins. No metadata. Just E2EE messages between peers. ## ๐Ÿš€ Installation ### ๐Ÿ”ง Global (from source) ```bash git clone https://github.com/carlostkd/k4li-chat.git cd k4li-chat-cli npm install npm link ``` This will globally install `k4li-chat` as a command-line tool. --- ## ๐Ÿ›  Usage To start chatting securely: ```bash k4li-chat ``` Youโ€™ll be prompted for: - **ntfy server** (e.g. `https://ntfy.sh` or your private instance we recommend to use our server.) - **room name** (this becomes the ntfy topic share that name and server with who you need to talk.) - **username** (shown to others in the chat) Once connected, your device will: - Generate an ECDH keypair - Broadcast your public key to the room - Derive AES keys with each peer securely - Begin encrypted communication --- ## ๐Ÿ’ฌ Chat Commands Inside the chat interface, you can use: | Command | Description | |------------------|--------------------------------------------------| | `/who` | List all connected users in the room | | `/msg NAME TEXT` | Send a private (DM) message to user `NAME` | | `/refresh` | Re-broadcast your public key in case of issues | | `/help` | Show this list of commands | --- ## ๐Ÿ” Security Model - Uses **ECDH (secp256k1)** for key exchange between peers - AES-256-CBC with SHA-256 derived keys for message encryption - All encryption and decryption happen **client-side only** - Messages and keys are never stored or processed by the server in plaintext - Supports **DM encryption** on a per-peer basis --- ## โœ… Example ``` โœ” Joined 'test' as alice ๐Ÿ” Secure chat ready โ€” waiting on peers... alice: hello world [12:42:55] bob: hi alice ๐Ÿ‘‹ [12:43:01] [DM] charlie: hey can we talk? ``` --- ## ๐Ÿงช Development To test locally: ```bash npm run dev ``` To publish (once ready): ```bash npm publish --access public ``` --- ## โค๏ธ Credits - Built with ๐Ÿ’ป by `Carlostkd` - Uses [ntfy](https://ntfy.sh) as backend transport - Open source, MIT licensed --- ## ๐Ÿ“Ž License [MIT](./LICENSE)