chrono-library-messenger 2.0.2
Messenger without data transmission
Requires Python: >=3.8

# Chrono-Library Messenger (CLM) <sup>v2.0.2</sup>

---

[![GitHub top language](https://img.shields.io/github/languages/top/smartlegionlab/chrono-library-messenger)](https://github.com/smartlegionlab/chrono-library-messenger)
[![PyPI - Downloads](https://img.shields.io/pypi/dm/chrono-library-messenger?label=pypi%20downloads)](https://pypi.org/project/chrono-library-messenger/)
[![GitHub release (latest by date)](https://img.shields.io/github/v/release/smartlegionlab/chrono-library-messenger)](https://github.com/smartlegionlab/chrono-library-messenger/)
[![GitHub](https://img.shields.io/github/license/smartlegionlab/chrono-library-messenger)](https://github.com/smartlegionlab/chrono-library-messenger/blob/master/LICENSE)

## 🌌 The Messaging Protocol That Transmits Nothing

A revolutionary Python console application implementing a cryptographic paradigm where **messages are not sent but discovered, and secrets are not stored but verified**. Based on the radical concept that secure communication requires neither data transmission nor secret storage.

> **✨ Philosophical Foundation:** This tool implements the paradigm-shifting ideas from [Chrono-Library Messenger](https://dev.to/smartlegionlab/i-created-a-messenger-that-doesnt-send-any-data-heres-how-it-works-4ecp) and [Messages That Have Always Been With Us](https://dev.to/smartlegionlab/the-magic-of-messages-that-have-always-been-with-us-48gp). Your messages aren't transmitted and your secrets aren't stored—they're mathematical truths waiting to be discovered.

## 🚀 What's New in v2.0.2

### 🔒 Security Revolution
- **Per-Chat Secret Authentication** - Each chat has its own secret phrase
- **Complete Chat Isolation** - No global message access, all management within chats
- **Secure Chat Creation** - New chats created securely via message reception
- **Enhanced Input Validation** - Strict chat name and secret validation

### 💬 Chat Management
- **In-Chat Message Management** - Full control (view, search, delete, restore) only within chat context
- **Advanced Search** - Search messages within specific chats
- **Trash System** - Recover accidentally deleted messages
- **Chat Secret Management** - Change secrets for individual chats

### 🎯 User Experience  
- **Streamlined Main Menu** - Cleaner interface focused on chat access
- **Interactive Chat Menus** - Comprehensive message management inside each chat
- **Secure Reception** - Create new chats by receiving messages with correct secret

## 🌟 Revolutionary Features

- 🚫 **Zero Data Transmission** - Only public pointers are shared
- 🔒 **Zero Secret Storage** - Master phrase exists only in memory during session
- 🗂️ **Chat Isolation** - Complete separation between conversation spaces  
- 🔐 **Per-Chat Secrets** - Unique authentication for each chat
- 📩 **Secure Chat Creation** - New chats via authenticated message reception
- 🔍 **In-Chat Search** - Advanced message search within chat context
- 🗑️ **Message Recovery** - Restore accidentally deleted messages
- 💾 **Local History Only** - Complete control over your data

![CLI Interface](https://github.com/smartlegionlab/chrono-library-messenger/raw/master/data/images/clm.png)

---

## 📨 Understanding Message Pointers

### What is a Message Pointer?
A message pointer is a JSON object that contains all the information needed to discover and decrypt a message, without containing the message itself or any sensitive secrets.

### Pointer Structure:
```json
{
  "e": 1758411713,        // epoch_index - timestamp of message creation
  "n": "IthOCeG9Vtet9zr_", // nonce - unique identifier for key generation  
  "d": "50fd56adf659c81909bf39747ebd7abd5800fc158d64aabbbc9e49c3641386f84babf8e" // ciphertext - encrypted message content
}
```

### 🔒 Why This is Secure:

#### Public Components (Safe to Share):
- **`e` (epoch_index)**: Public timestamp - reveals only when message was created
- **`n` (nonce)**: Public unique value - ensures each encryption is unique
- **`d` (ciphertext)**: Encrypted data - useless without the secret key

#### Secret Components (Never Shared):
- **Chat Secret**: The phrase known only to chat participants
- **Decryption Key**: Generated dynamically from secret + public components

### 🛡️ Security Guarantees:

1. **Zero Secret Exposure**: No secrets are ever stored or transmitted
2. **Perfect Forward Secrecy**: Each message uses unique encryption key
3. **Brute Force Protection**: Without chat secret, decryption is impossible
4. **Metadata Minimalism**: Only essential public information is shared

### 💡 How It Works:

```python
# To decrypt a message, you need:
decryption_key = generate_key(
    chat_secret,    # 🚨 Known only to participants
    epoch_index,    # 📍 Public timestamp
    nonce,          # 🎲 Public unique value
    ciphertext_length
)

# Without the chat secret:
decryption_key = generate_key(
    "wrong_guess",  # ❌ Incorrect secret
    epoch_index,    # ✅ Public
    nonce,          # ✅ Public  
    ciphertext_length
)  # → Generates wrong key → Decryption fails! 🛑
```

### 🌐 Real-World Analogy:

Think of a message pointer like **coordinates to a treasure chest**:
- 📍 **Coordinates (public)**: Anyone can see where to look
- 🔑 **Key (secret)**: Only you can open the chest
- 🎁 **Contents (encrypted)**: Protected until opened with correct key

### 🚀 Sharing Safely:

You can share message pointers:
- ✅ In public channels
- ✅ Via email or messaging apps  
- ✅ On social media
- ✅ Through any communication medium

The message remains protected until someone with the correct chat secret uses the pointer to discover and decrypt it!

> **Remember**: The security doesn't come from hiding the pointer, but from the mathematical impossibility of deriving the secret from public components.

---

## 🔐 The Authentication Revolution

### How It Works:
1. **Per-Chat Secrets**: Each chat has its own secret phrase
2. **Setup**: Create chat name + chat secret → generates chat secret hash
3. **Authentication**: Enter chat secret → verifies against stored hash
4. **Isolation**: No access to chat without correct secret
5. **Security**: Compromised chat secret doesn't affect other chats

### Security Advantages:
- 🔒 **Compartmentalized Security** - Breach affects only single chat
- 🚫 **No Cross-Chat Access** - Secrets are chat-specific
- 🔑 **Cryptographic Proof** - Zero-knowledge style authentication per chat
- ⚡ **Session Caching** - Secrets cached during session for convenience

---

## 📦 Installation

```bash
pip install chrono-library-messenger
```

## 🧙‍♂️ Quick Start: Your First Session

### 1. First Launch - Initial Setup
```bash
clm
```
The application will guide you through:
- Creating your username
- Setting your master secret phrase
- Generating secure public key

### 2. Create Your First Chat
```bash
# From main menu:
2. ➕ Create a new chat
```
- Choose chat name
- Set chat secret phrase
- Confirm secret phrase

### 3. Send and Receive Messages
```bash
# Enter chat → Send message
# Or receive message to create new chat
4. 📩 Receive message (new chat)
```

### 4. Manage Messages Within Chats
```bash
# Enter any chat to access:
3. 📜 View history
4. 🔍 Search messages  
5. 🗑️ Manage messages
```

## 🏗️ Core Architecture

### The Triple Paradox:
1. **Synchronous Discovery Without Transmission**
   - Messages emerge from mathematical space when parameters align
   - No content ever leaves your device

2. **Authentication Without Storage**  
   - Prove knowledge without revealing the secret
   - Verify identity without storing credentials

3. **Compartmentalized Security**
   - Each chat is a separate security domain
   - No global access to all messages

### Cryptographic Foundation:
- **HMAC_DRBG** - NIST-compliant deterministic random bit generator
- **SHA-256** - Industry-standard cryptographic hashing
- **XOR Cipher** - Information-theoretic security when key is random
- **Per-Chat Authentication** - Individual secrets for each conversation space

## 🛡️ Security Architecture

### What's Stored (Safe):
- `public_key` - Cryptographic proof of master secret knowledge
- `username` - Your public identity
- `chat_secret_hash` - Hashed chat secrets (not reversible)
- `message_history` - Your local encrypted conversation records

### What's NEVER Stored (Secure):
- `master_secret` - Your main authentication phrase
- `chat_secrets` - Individual chat secrets (only hashes stored)
- `decryption_keys` - Message decryption material
- `session_tokens` - Temporary access credentials

### What's Shared (Public):
- `pointers` - JSON objects containing (epoch, nonce, ciphertext)
- `chat_names` - Public conversation identifiers
- `timestamps` - Message discovery time references

## 📖 Advanced Usage

### Chat Management:

**Create Secure Chats:**
```bash
# Each chat is a separate security domain
+ Personal Conversations
+ Work Projects
+ Secret Groups
```

**Message Management Within Chats:**
```bash
# Full control inside each chat:
📜 View complete history
🔍 Search messages by content  
🗑️ Manage deleted messages
🧹 Clear entire chat history
```

**Secure Message Reception:**
```bash
# Create new chats by receiving messages:
Enter payload + correct secret → Auto-creates chat
```

### Security Features:

**Change Chat Secrets:**
```bash
# Rotate secrets for enhanced security
🔐 Change chat secret → Enter new phrase
```

**Complete Data Control:**
```bash
# Full ownership of your data:
❌ Delete chat → Removes all messages permanently
🗑️ Manage messages → Restore or permanent delete
```

## 🔄 Ecosystem Integration

### Built on Proven Foundations:
- **[SmartPassLib](https://github.com/smartlegionlab/smartpasslib/)** - Deterministic cryptography core
- **Zero-Storage Principle** - No secrets, no problems
- **Cross-Platform Compatibility** - Universal Python implementation

### Consistency Framework:
All components follow the same security principles:
- Deterministic cryptography
- Zero secret storage
- Local data ownership
- User-controlled access
- Compartmentalized security

## ⚠️ Security Considerations

**Important: This remains a Proof-of-Concept for research and education.**

### Enhanced Security in v2.0.2:
- ✅ **Per-chat secrets** - Compartmentalized security domains
- ✅ **No global message access** - All management within chat context
- ✅ **Secure chat creation** - New chats via authenticated reception
- ✅ **Input validation** - Strict chat name and secret validation
- ✅ **Session caching** - Convenience without persistent storage

### Current Limitations:
- **Metadata Visibility** - Timestamps remain public
- **Pre-Shared Knowledge** - Initial chat secrets must be established securely
- **No Forward Secrecy** - Chat secret compromise reveals historical messages
- **Basic Integrity** - Additional authentication codes could enhance protection

## 🤝 Supported Platforms

- **Linux** - Native console support
- **Windows** - Command Prompt and PowerShell
- **macOS** - Terminal and iTerm2
- **Android** - Termux environment
- **BSD** - Full compatibility

## 📊 Database Structure

**Location**: `~/.config/clm/clm.db` (fully portable)

Tables:

- config - Public key and username (NO SECRETS)

- chats - Conversation spaces with secret hashes (NOT actual secrets)

- messages - Encrypted message history with chat isolation

**Security**: No database encryption - relies on system security and cryptographic protection

## 🚀 Production Considerations

For serious deployment consider adding:
- Database encryption layer
- Secure secret exchange protocol
- Forward secrecy mechanisms
- Message authentication codes
- Formal security audit
- Backup and recovery procedures

## 📜 License & Disclaimer

BSD 3-Clause License

Copyright (c) 2025, Alexander Suvorov

```
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF Such DAMAGE.
```

**Legal Disclaimer:** Chrono-Library Messenger is a proof-of-concept for academic research and educational purposes only. Users are solely responsible for compliance with all applicable laws and regulations regarding cryptography and secure communications in their jurisdiction.

## 🌟 Join the Security Revolution

This isn't just another messaging app—it's a fundamental rethinking of digital security:

**From storing secrets → to proving knowledge**  
**From transmitting data → to discovering truths**  
**From trusting providers → to owning your security**  
**From global access → to compartmentalized security**

Your messages were always there. Your security was always possible. Now you have the tools to discover both.

**What do you think? Is this the future of digital security? Let's discuss on [Dev.to](https://dev.to/smartlegionlab) or [GitHub](https://github.com/smartlegionlab/chrono-library-messenger)!**

---

*Discover more revolutionary projects at [Smart Legion Lab](https://github.com/smartlegionlab)*

## 🔧 Development & Contributing

```bash
# Setup development environment
git clone https://github.com/smartlegionlab/chrono-library-messenger.git
cd chrono-library-messenger
pip install -e .

# Contribution welcome!
# Focus areas: security audit, UI improvements, documentation
```

*Together, we're building a future where security means never having to store a secret and every conversation is its own protected realm.*