TSM - Telegram Session Manager

Advanced session management system for Telegram with hardware security, mobile integration, and post-quantum cryptography support.

⚡ Quick Start

# Clone repository
git clone https://github.com/your-org/tsm-advanced.git
cd tsm-advanced

# Setup environment
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Initialize configuration
cp config/tsm.example.yaml config/tsm.yaml
python -m tsm.database.init

# Run TSM
python -m tsm

📄 Repository Guidelines

For contributor workflow, coding standards, and testing expectations, read AGENTS.md.

🧰 Desktop Client Bundle

To generate a turnkey bundle similar to 64Gram, run:

./scripts/build_tsm_client.sh

This produces dist/tsm-client/ containing a pre-populated virtual environment, the QUANTUMGUARD mock gRPC service, and the Textual desktop client. Launch everything with run_client_with_server.sh, or run the components individually via run_server.sh and run_client.sh.

🔄 Migration & Session Helpers

python tools/tsm_wrap_telegram.py --list — discover existing Telegram Desktop tdata directories. Drop the --list flag to import all detected sessions into TSM.
python tools/tsm_switch_session.py [--session-id ID] [--launch] — activate a stored session (interactive when no ID is supplied) and optionally relaunch Telegram Desktop.

🌐 Remote Session API

Run ./scripts/run_api_server.sh (requires fastapi and uvicorn in the venv) to expose a REST interface on port 8080. Key endpoints:
- POST /auth/challenge (body: { "username": "alice" }) – start a YubiKey challenge and receive hex challenge data.
- POST /auth/verify with the challenge response to obtain a bearer token.
- GET /sessions and POST /switch – list and activate sessions using the token.

A lightweight Python SDK is available in sdk/tsm_client.py:

from sdk.tsm_client import TSMApiClient

client = TSMApiClient('http://localhost:8080')
challenge = client.create_challenge('alice')
# obtain YubiKey response using your preferred method
token = client.verify(challenge.challenge_id, yubikey_response)
print(client.list_sessions())

🎯 Core Features

Security

Hardware Security: YubiKey 5 Series integration for multi-factor authentication
Encryption: AES-256-GCM with hardware-backed key storage
Post-Quantum Ready: CRYSTALS-Kyber and Dilithium algorithm support
Zero-Knowledge Proofs: Prove session ownership without revealing content

Session Management

Multi-Session Support: Manage unlimited Telegram sessions
Instant Switching: Change active sessions in <100ms
Encrypted Backups: Automatic versioned backups with compression
Session Isolation: Complete data separation between sessions

Mobile Integration

Native Apps: iOS and Android companion applications
P2P Sync: Direct device-to-device synchronization
Remote Control: Manage desktop sessions from mobile
Biometric Auth: Face ID, Touch ID, and fingerprint support

Operational Features

gRPC API: High-performance network protocol
Real-time Monitoring: Prometheus metrics and Grafana dashboards
Audit Logging: Complete activity tracking
Automated Scheduling: Time-based session activation

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                      TSM ECOSYSTEM                           │
├─────────────────────────────────────────────────────────────┤
│  ┌──────────┐     ┌──────────┐     ┌──────────┐           │
│  │ Desktop  │◄────┤  Mobile  │────►│ YubiKey  │           │
│  │  Client  │     │   Apps   │     │ Hardware │           │
│  └────┬─────┘     └────┬─────┘     └────┬─────┘           │
│       │                 │                 │                  │
│       ▼                 ▼                 ▼                  │
│  ┌─────────────────────────────────────────────┐           │
│  │            gRPC API Server                   │           │
│  │  ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐      │           │
│  │  │ Auth │ │Crypto│ │Backup│ │Mobile│      │           │
│  │  └──────┘ └──────┘ └──────┘ └──────┘      │           │
│  └─────────────────────────────────────────────┘           │
│       │                 │                 │                  │
│       ▼                 ▼                 ▼                  │
│  ┌──────────┐     ┌──────────┐     ┌──────────┐           │
│  │ SQLite   │     │Encrypted │     │  Audit   │           │
│  │    DB    │     │ Storage  │     │   Logs   │           │
│  └──────────┘     └──────────┘     └──────────┘           │
└─────────────────────────────────────────────────────────────┘

📋 Requirements

Hardware

Desktop: 4GB RAM, 10GB storage, USB ports
Mobile: Android 8.0+ or iOS 14+, NFC capability
Security: YubiKey 5 Series (5C, 5Ci, or 5 NFC)

Software

Python 3.9+
Docker & Docker Compose
OpenSSL 1.1.1+
Git

🚀 Installation

1. Basic Setup

# Install system dependencies
sudo apt-get install pcscd libpcsclite-dev swig

# Setup TSM
./scripts/install.sh

# Configure YubiKey
python -m tsm.yubikey.setup

2. Generate Certificates

# Create CA and server certificates
./scripts/generate_certs.sh

# Generate mobile client certificates
./scripts/generate_mobile_certs.sh

3. Deploy Services

# Start with Docker Compose
docker-compose up -d

# Or use systemd
sudo systemctl enable --now tsm

🔐 Security Configuration

YubiKey Setup

# config/yubikey.yaml
yubikey:
  require_presence: true
  require_touch: true
  modes:
    - fido2_resident
    - piv_encryption

Encryption Settings

# config/tsm.yaml
security:
  encryption_enabled: true
  require_yubikey: true
  auto_lock_minutes: 15

📱 Mobile Apps

iOS

cd mobile/ios
pod install
open TSM.xcworkspace
# Build in Xcode

Android

cd mobile/android
./gradlew assembleRelease
# APK in app/build/outputs/apk/

🧪 Testing

# Run all tests
pytest tests/ -v --cov=tsm

# Security tests
python -m security.scanner --target localhost:50051

# Load testing
python -m tests.load.test_performance

📊 Monitoring

Access monitoring dashboards:

Prometheus: http://localhost:9090
Grafana: http://localhost:3000
API Metrics: http://localhost:8080/metrics

🛠️ Advanced Usage

YubiKey-Protected Operations

from tsm_enhanced import TelegramSessionManager
from tsm_yubikey import TSMYubiKeyIntegration

# Initialize
tsm = TelegramSessionManager(config)
yubikey = TSMYubiKeyIntegration(tsm, yk_config)

# Protected session switch
if await yubikey.require_authentication("switch_session"):
    await yubikey.yubikey_protected_switch("work_account")

Mobile Remote Control

# From mobile app
client = TSMobileClient()
await client.connect("desktop.local", 50051)
sessions = await client.list_sessions()
await client.switch_session("personal_account")

🗺️ Roadmap

v3.0 (Q1 2025)

Post-quantum cryptography
Hardware security module support
Zero-knowledge proofs

v4.0 (Q2-Q3 2025)

AI-powered security analysis
Distributed session storage
Session virtualization
Advanced automation

Future

Quantum key distribution
Decentralized identity
Homomorphic encryption

🏢 Enterprise Features

LDAP/AD Integration: Centralized user management
Compliance Reporting: GDPR, SOC2 audit trails
High Availability: Multi-node deployment
API Rate Limiting: DDoS protection

🐛 Troubleshooting

YubiKey Not Detected

# Fix USB permissions
sudo usermod -a -G plugdev $USER
sudo udevadm control --reload-rules

Mobile Connection Issues

# Check firewall
sudo ufw allow 50051/tcp
# Verify certificates
openssl verify -CAfile certs/ca.crt certs/server.crt

📚 Documentation

🤝 Contributing

This is a classified project. Contributions require security clearance and signed NDAs.

⚖️ License

Proprietary - See LICENSE for details.

🚨 Security

Report vulnerabilities to: security@tsm.local
PGP Key: 0xDEADBEEF
Bug Bounty Program: Available for authorized researchers

WARNING: This software is classified TOP SECRET. Unauthorized access, distribution, or reverse engineering is prohibited and may result in severe legal consequences.

Built with 🔐 by the TSM Team