bstkchat 2.1.0

Enhanced Terminal-based Encrypted Chat Application with threading, reactions, 2FA, file sharing, and more.

BSTK Chat (bstkchat) - v2.0

Enhanced Terminal-based Encrypted Chat with threading, reactions, 2FA, file sharing, polls, and more.

bstkchat is a real-time, terminal-based, zero-configuration collaborative chat client. Anyone who launches the client and joins using the same Room ID will instantly join a shared, encrypted room to text and exchange thoughts.

🚀 What's New in v2.0

• 20 Major Features across User Experience, Communication, Privacy & Security, and Persistence
• SQLite Database - Full message history with search
• Message Reactions & Polls - Emoji reactions and voting
• Message Threading - Organized conversations
• Typing Indicators - See who's typing
• Read Receipts - Know when messages are read
• 2FA Authentication - TOTP-based security
• Admin Controls - Mute, kick, ban users
• RSA Signing - Message authenticity verification
• File Sharing - Share files over chat
• Voice Messages - Send audio messages
• Message TTL - Auto-expiring messages
• Archive/Export - Download chat history (JSON/CSV)
• User Profiles - Bio, avatar, location info
• Draft Auto-Save - Never lose your message

Features

Core Features

• Zero Configuration: Connects instantly to a public MQTT infrastructure—no servers to set up
• Non-blocking Input: Messages arriving dynamically will never corrupt your typing, thanks to prompt_toolkit
• Memorable Auto-Rooms: Auto-generates fun phonetic room names like quantum-beacon-55
• Deterministic Color Codes: Users get static text colors for easy conversation following
• Command Architecture: 50+ slash commands for advanced functionality

User Experience

• Message Search (/search <query>) - Full-text search through history
• Message History (/history [limit]) - View past messages
• User Profiles (/profile [user]) - View user bios and stats
• Typing Indicators - Real-time "user is typing..." notifications
• Message Reactions (/react <id> <emoji>) - React with emojis
• Draft Auto-Save - Automatic message drafts to avoid data loss
• Rich Formatting - Full markdown support with code blocks

Communication

• Message Threading (/thread <id> <reply>) - Organized conversations
• Polls (/poll <q> <opt1> <opt2>) - Create and vote on polls
• File Sharing (/file <path>) - Share files over MQTT
• Voice Messages (/voice <seconds>) - Send audio messages
• Direct Messages (/msg <user> <text>) - Private encrypted DMs
• Channels (/channel <name>) - Channel-like organization

Privacy & Security

• End-to-End Encryption - AES-GCM room encryption + X25519 DM encryption
• RSA Message Signing - Verify message authenticity
• 2FA Authentication (/2fa, /verify <code>) - Time-based one-time passwords
• Read Receipts - Know who read your messages
• Message TTL - Auto-expiring messages
• Admin Controls - Mute, kick, or ban users
  • /mute <user> - Hide user's messages
  • /kick <user> - Remove from room
  • /ban <user> - Permanent ban

Persistence

• Local SQLite Database - Full message history
• Archive Export (/archive) - Export room to JSON
• Multiple Formats (/export csv|json) - CSV or JSON export
• User Profiles - Bio, avatar, location, website
• Multi-Session Sync - History available across sessions

Installation

Method 1: Local Pip Installation (Recommended)

git clone https://github.com/yourusername/bstkchat.git
cd bstkchat
pip install .

Then run from anywhere:

bstkchat

Method 2: Running from Source

pip install -r requirements.txt
python -m bstkchat.cli

All Slash Commands

Category	Command	Action
Messaging	/msg <user> <text>	Send direct message
	/thread <id> <reply>	Reply in thread
	/react <msg_id> <emoji>	Add emoji reaction
	/typing	Send typing indicator
Room	/room <id> [password]	Switch room
	/topic <text>	Set room topic
	/channel <name>	Switch channel
User	/nick <name>	Change nickname
	/profile [user]	View profile
	/status <text>	Set status message
	/who or /users	List online users
Search & History	/search <query>	Search messages
	/history [limit]	View message history
Drafts	/draft <text>	Save draft
	/drafts	List drafts
Polls	/poll <q> <o1> <o2>	Create poll
	/vote <id> <option>	Vote in poll
Files	/file <path>	Share file
	/download <id>	Download file
Voice	/voice <seconds>	Send voice message
Admin	/mute <user>	Mute user
	/unmute <user>	Unmute user
	/kick <user>	Remove from room
	/ban <user>	Ban user
	/unban <user>	Unban user
Security	/2fa	Enable 2FA
	/verify <code>	Verify 2FA code
Archive	/archive	Archive room
	/export csv|json	Export messages
Utility	/help	Show command help
	/clear	Clear screen
	/log	Toggle logging
	/broker <host> [port]	Change MQTT broker
	/exit	Leave chat

Project Structure

bstkchat/
├── __init__.py              # Package init
├── cli.py                   # Main ChatClient + entry point
├── models.py                # Data classes (Message, User, Room, etc.)
├── database.py              # SQLite database layer
├── crypto.py                # Encryption + 2FA + RSA signing
├── network.py               # MQTT wrapper
├── ui.py                    # Terminal UI with Rich
├── commands.py              # Command handler (50+ commands)
├── cli_backup.py            # v1 backup
└── ...

Database Schema

Automatically created at ~/.bstkchat/chat.db with tables for:

• Messages (with reactions, threading, signatures)
• Users (profiles, keys, settings)
• Rooms (configuration, topics, members)
• Drafts (auto-save)
• Polls (questions and votes)
• File Shares (with metadata)
• Voice Messages
• Admin Actions (mute, kick, ban)
• Read Receipts
• User Profiles (extended info)

Security Model

1. Transport Encryption: MQTT over TLS (optional)
2. Room Encryption: AES-256-GCM with password-derived key
3. DM Encryption: X25519 ECDH for key exchange + AES-GCM
4. Message Signing: RSA-2048 for authenticity
5. 2FA: TOTP with backup codes
6. Admin Controls: Client-side enforcement of mute/kick

Configuration

Default MQTT broker: broker.hivemq.com:1883

Switch at runtime: /broker mosquitto.example.com 8883

Or set in config file (future): ~/.bstkchat/config.yaml

Dependencies

• paho-mqtt>=1.6.1 - MQTT client
• rich>=13.0.0 - Terminal UI
• prompt-toolkit>=3.0.0 - Non-blocking input
• cryptography>=41.0.0 - Encryption
• pyotp>=2.9.0 - 2FA/TOTP
• reportlab>=4.0.0 - PDF export (future)

Performance

• Lightweight terminal UI
• Efficient SQLite queries with indexing
• Background task for heartbeat/cleanup (15s interval)
• Typing indicator auto-cleanup (3s timeout)
• Message expiration cleanup

Roadmap

• Web UI for browser access
• Mobile app port
• Server mode with persistence
• Plugin system for custom commands
• Voice call support
• Video messages
• Desktop notifications
• Message reactions with skin tone variants
• Community plugins marketplace

Contributing

Pull requests welcome! Areas for contribution:

• New message types
• Additional export formats (PDF, Excel)
• Custom themes
• Mobile UI
• Documentation
• Tests

License

MIT License - See LICENSE file

---

For detailed feature documentation, see FEATURES.md