🎨 Terminal Chat

A simple, secure, and feature-rich terminal-based chat application with end-to-end encryption, private file sharing, and multi-client support.

---

⚠️ Important Disclaimers

🤖 AI-Generated Project

This entire project was created by AI using VS Codium with the Roo Code extension, powered by Anthropic Claude Sonnet 4.5.

• ✨ 100% AI-coded - Every line of code, documentation, tests, and configuration
• 🎯 Prompt-driven development - The author only wrote prompts, no actual code
• 🤖 AI architecture - Designed, implemented, and tested by AI
• 📝 AI documentation - All README files, guides, and comments generated by AI

This project demonstrates the current capabilities of AI-assisted development and serves as an example of what can be achieved through careful prompting and iterative refinement.

🔒 Network Usage Warning

⚠️ PRIVATE NETWORKS ONLY - DO NOT USE ON PUBLIC INTERNET ⚠️

This application is designed for private, trusted networks only (home LANs, office networks, VPNs). It is NOT intended for public internet deployment without significant additional security measures.

Why private networks only?

• 🚫 No TLS/SSL transport encryption (data encrypted but no secure channel)
• 🚫 No authentication system (password-only, no user accounts)
• 🚫 No rate limiting (vulnerable to spam/DoS)
• 🚫 No input validation hardening for internet threats
• 🚫 No protection against sophisticated attacks

If you must deploy publicly:

1. Use a VPN (WireGuard, OpenVPN) to create a private network
2. Add a reverse proxy with TLS (nginx, traefik)
3. Implement rate limiting and fail2ban
4. Use strong, unique passwords
5. Monitor logs actively
6. See Security Assessment

Recommended use cases:

• ✅ Home networks
• ✅ Office LANs
• ✅ VPN-connected users
• ✅ Development/testing
• ✅ Educational purposes
• ❌ Public internet (without additional security)

---

✨ Features

• 🔐 End-to-End Encryption - AES-256-CBC encryption for all messages and files
• 👥 Multi-Client Support - Real-time chat with multiple users simultaneously
• 📁 Smart File Sharing - Share files publicly or privately with specific users
• 🎯 Permission System - Granular access control for file sharing
• 🌈 Color-Coded Messages - Easy-to-follow conversations with unique colors per user
• 🔒 Unique Usernames - No duplicate names allowed for secure identification
• 📊 Complete Logging - Server-side audit trail for all operations
• 🌍 Multi-Language - English and German documentation
• 🧪 Fully Tested - 27 unit and integration tests (100% pass rate)

🚀 Quick Start

Installation

# Clone the repository
git clone https://github.com/maxron84/Terminal-Chat-Program.git
cd Terminal-Chat-Program

# No dependencies needed! Pure Python 3.6+

Running the Chat

Interactive Mode (Easiest - Cross-Platform):

python3 bin/terminal-chat.py

Docker Mode (Production-Ready):

# Configure
cp .env.example .env
nano .env  # Set strong password

# Deploy
docker-compose up -d

# Connect from any machine
python3 bin/terminal-chat.py

Troubleshooting Docker:

# If containers restart or encounter errors:
./docker-rebuild.sh

See Docker Deployment Guide for complete guide.

Command Line Mode:

# Start server
python3 src/main.py listen 4444 mypassword Admin

# Connect as client
python3 src/main.py connect localhost 4444 mypassword Alice

📖 Usage

Basic Chat

Once connected, simply type messages and press Enter:

[Alice] > Hello everyone!
[Bob] > Hi Alice! How are you?
[Alice] > Great! Let me share a file with you...

Commands

Command	Description	Example	Available To
/upload <file>	Upload file (public)	/upload report.pdf	All users
/upload <file> @user	Upload file privately	/upload contract.pdf @Bob	All users
/download <file>	Download file from shared	/download report.pdf	All users
/list	List shared files	/list	All users
/inbox	List received private files	/inbox	All users
/outbox	List files ready to upload	/outbox	All users
/help	Show available commands	/help	All users
/quit	Exit chat	/quit	All users

Note: The server (admin) can also receive private files from clients in its inbox folder!

File Sharing Examples

Public File (Everyone can access):

# 1. Put file in data/outbox/
cp myfile.pdf data/outbox/

# 2. Upload in chat
[Alice] > /upload myfile.pdf
✓ File uploaded

# 3. Anyone can download
[Bob] > /download myfile.pdf
✓ Downloaded to data/inbox/myfile.pdf

Private File (Only for specific user):

# 1. Put file in data/outbox/
cp confidential.pdf data/outbox/

# 2. Upload privately
[Alice] > /upload confidential.pdf @Bob
✓ File uploaded privately for Bob

# 3. Only Bob can download
[Bob] > /download confidential.pdf
✓ Downloaded

[Charlie] > /download confidential.pdf
✗ Error: Private file (from Alice for Bob)

🏗️ Project Structure

Terminal-Chat-Program/
├── bin/
│   ├── terminal-chat.py        # Interactive launcher (cross-platform) ⭐
│   ├── instructions.txt    # Quick reference (EN)
│   └── anleitung.txt       # Quick reference (DE)
├── src/
│   ├── main.py             # Main entry point ⭐
│   └── lib/                # Core library modules
│       ├── __init__.py
│       ├── utils.py        # Utilities & colors
│       ├── encryption.py   # AES-256-CBC encryption
│       ├── server.py       # Multi-client server
│       ├── client.py       # Chat client
│       └── file_permissions.py  # Access control
├── tests/
│   └── test_chat.py        # 27 unit & integration tests
├── docs/
│   ├── CONTRIBUTING.md     # Contribution guidelines
│   ├── SECURITY.md         # Security policy
│   ├── CHANGELOG.md        # Version history
│   ├── DOCKER_DEPLOYMENT.md # Docker guide
│   ├── MODULAR_STRUCTURE.md # Architecture
│   ├── TEST_DOCUMENTATION.md # Testing
│   ├── USER_MANUAL.txt     # User manual (EN)
│   ├── BENUTZER_HANDBUCH.txt # User manual (DE)
│   └── security/           # Security docs
│       ├── SECURITY_ASSESSMENT.md
│       └── SECURITY_ENHANCEMENT_CONCEPT.md
├── data/                   # User data (auto-created)
│   ├── inbox/             # Downloaded files
│   ├── outbox/            # Files to upload
│   ├── shared/            # Shared folder on server
│   └── file_permissions.json  # Access metadata
└── logs/                   # Server logs (auto-created)
    └── chat_server_*.log

🔧 Requirements

Native Installation

• Python 3.6+ (usually pre-installed on Linux/Mac)
• OpenSSL (for encryption - usually pre-installed)

No external Python packages required!

Docker Installation (Alternative)

• Docker 20.10+
• Docker Compose 1.29+ (optional but recommended)

Perfect for production deployments!

🧪 Testing

Run the comprehensive test suite:

cd tests
python3 test_chat.py

Expected output:

Ran 27 tests in 0.330s

OK ✅

Tests run: 27
Successes: 27
Failures: 0
Errors: 0

📚 Documentation

User Guides

• User Manual - Complete guide (EN)
• Benutzerhandbuch - Vollständige Anleitung (DE)
• Docker Deployment - Container deployment

Technical Details

• Architecture - Code structure
• Testing - Test strategy
• Security - Security policy
• Contributing - Contribution guide
• Changelog - Version history

Quick Reference

• Commands (EN) - Quick reference
• Befehle (DE) - Kurzreferenz

🔒 Security Features

Encryption

• Algorithm: AES-256-CBC with PBKDF2 key derivation
• Transport: Encrypted payload over TCP
• Files: Base64-encoded and encrypted during transfer

Access Control

• Username Uniqueness: No duplicate names allowed
• File Permissions: Granular control over who can access what
• Audit Trail: Complete server-side logging
• Private Sharing: One-to-one file transfers

What's Logged

• User connections/disconnections
• File uploads/downloads
• Permission checks
• Failed authentication attempts
• All server operations

🌐 Multi-Language Support

Documentation Languages

• 🇬🇧 English
• 🇩🇪 Deutsch (German)

Add Your Language

Contributions for additional languages welcome! See bin/instructions.txt as template.

🛠️ Development

Running from Source

# As library
python3 -c "from src.lib import ChatServer, ChatClient"

# Direct execution
python3 src/main.py listen 4444 pass Admin

Docker Development

# Build image
docker build -t terminal-chat:dev .

# Run with live code mounting
docker run -it --rm \
  -v $(pwd)/src:/app/src \
  -p 4444:4444 \
  terminal-chat:dev listen 4444 pass Admin

# Run tests in container
docker run --rm terminal-chat:dev python3 tests/test_chat.py

Running Tests

# All tests
python3 tests/test_chat.py

# Specific test class
python3 -m unittest tests.test_chat.TestEncryption

# With pytest (if installed)
pytest tests/test_chat.py -v

Code Style

The project follows PEP 8 guidelines with:

• 4-space indentation
• Max line length: 100 characters
• Docstrings for all functions/classes

📊 Test Coverage

Component          Tests   Status
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Encryption         8       ✅ Pass
Client             5       ✅ Pass
Server             2       ✅ Pass
File Ops           2       ✅ Pass
Permissions        7       ✅ Pass
Integration        2       ✅ Pass
Utilities          2       ✅ Pass
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Total              27      ✅ All Pass

🎯 Use Cases

Family & Friends

• Private messaging without corporate platforms
• Share family photos securely
• Coordinate events with file sharing

Small Teams

• Quick team communication
• Share project files
• Development team coordination

Education

• Class discussions
• Assignment submission
• Study group collaboration

Self-Hosting

• Complete control over your data
• No external dependencies
• Run on any Linux/Mac/Windows machine

⚠️ Security Considerations

For Local Networks

• ✅ Perfect for home/office LANs
• ✅ Encrypted message content
• ✅ No external dependencies

For Internet Deployment

• ⚠️ Consider adding TLS transport layer
• ⚠️ Implement rate limiting
• ⚠️ Use VPN for additional security
• 📖 See Security Assessment

🎨 Screenshots

┌─────────────────────────────────────────┐
│ Terminal Chat                          │
├─────────────────────────────────────────┤
│ [10:30:15] Alice: Hello everyone!       │
│ [10:30:20] Bob: Hi Alice!               │
│ [10:30:25] Alice: Check out report.pdf  │
│ [10:30:30] *** Alice uploaded file:     │
│            report.pdf ***               │
│ [10:30:35] Bob: /download report.pdf    │
│ [10:30:36] ✓ Downloaded to inbox/       │
│                                         │
│ [Alice] > _                             │
└─────────────────────────────────────────┘

📝 License

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

🙏 Acknowledgments

• Built with Python's standard library
• Uses OpenSSL for encryption
• Inspired by the need for simple, secure communication

📧 Contact

• Issues: GitHub Issues
• Discussions: GitHub Discussions

🗺️ Roadmap

Version 2.0 (Planned)

• TLS/SSL transport encryption
• User authentication system
• Session management
• Rate limiting
• Web-based GUI

Version 3.0 (Future)

• Voice chat support
• Video sharing
• Mobile apps
• Plugin system

🤝 Contributing

Contributions welcome! Please:

• Fork the repo and create a feature branch
• Run tests before submitting PR
• Follow PEP 8 style guidelines
• Update documentation as needed

See CONTRIBUTING.md for detailed guidelines.

🔒 Security

Report vulnerabilities via GitHub Security Advisories (not public issues).

This project is for private networks only. It lacks:

• TLS/SSL transport encryption
• Rate limiting
• Enterprise-grade security features

See SECURITY.md for full security policy.

📋 Changelog

v1.0.0 (2025-11-02)

• Initial release
• Multi-client encrypted chat
• Private file sharing
• Docker deployment
• 27 passing tests

See CHANGELOG.md for detailed version history.

---

⭐ Star This Project

If you find this project useful, please consider giving it a star!

---

Made with ❤️ by AI (Claude Sonnet 4.5) + Human prompts

Happy Chatting! 🎉