televault 3.1.2

Unlimited cloud storage using Telegram MTProto. No local DB - everything on Telegram.

  ██╗░██████╗  
  ██║██╔════╝  
  ██║██║░░██╗  
  ██║██║░░██║  
  ██║╚█████╔╝  
  ╚═╝░╚════╝░  

Unlimited cloud storage via Telegram

Encrypt → Chunk → Upload to your private Telegram channel.
No servers. No limits. No trust required.

pip install televault  ·  Docs  ·  Quick Start  ·  Architecture

---

Why TeleVault?

	TeleVault	Cloud Storage
Cost	Free (Telegram account)	$5-30/month
Storage Limit	Unlimited	15 GB - 2 TB
Encryption	AES-256-GCM client-side	Server-side or none
Trust Model	Zero-trust (you hold the key)	Trust the provider
File Size	Up to 2 GB per file	Varies
Speed	Parallel chunk uploads	Single connection

TeleVault turns a private Telegram channel into encrypted, unlimited cloud storage. No local database — everything lives as pinned messages and reply chains in the channel. Your password never leaves your machine.

---

Features

• End-to-end encryption — AES-256-GCM with scrypt key derivation. Telegram only sees ciphertext.
• Parallel transfers — Upload 3 chunks, download 5 chunks simultaneously.
• Resumable uploads/downloads — CRC32-protected progress files survive interruptions.
• Data safety — Atomic config writes, sequential index access (asyncio.Lock), cached index lookups, crash-safe delete/upload/stream.
• Git-like backups — Incremental snapshots with retention policies.
• FUSE mount — Mount your vault as a local filesystem with on-demand streaming.
• WebDAV server — Access files over HTTP from any device.
• Terminal UI (beta) — Interactive file browser with detail panel.
• Piping — cat file | tvt push -, tvt cat file | jq, tvt ls --json.
• Auto-backup — Schedules, systemd timers, file watching.
• Garbage collection — Find and remove orphaned messages (dry-run by default).

---

Installation

pip install televault

# Optional extras
pip install televault[fuse]       # FUSE mount support (Linux/macOS)
pip install televault[webdav]     # WebDAV server
pip install televault[preview]    # Image preview (Pillow)
pip install televault[dev]        # Development tools
pip install -e ".[dev,fuse,webdav,preview]"  # Everything

Python 3.11+ is required.

---

Quick Start

# 1) Get Telegram API credentials at https://my.telegram.org
export TELEGRAM_API_ID=your_api_id
export TELEGRAM_API_HASH=your_api_hash

# 2) Login
tvt login

# 3) Set up storage (interactive — validates channel, sends test message)
tvt setup

# 4) Upload
tvt push photo.jpg

# 5) List
tvt ls

# 6) Download
tvt pull photo.jpg

# 7) Stream to stdout
tvt cat photo.jpg > photo_copy.jpg

# 8) Preview without full download
tvt preview photo.jpg

# 9) Check channel info
tvt channel

---

Usage

Core Commands

tvt push <file>              # Upload a file (use - for stdin)
tvt pull <file>              # Download (use -o - for stdout)
tvt ls [--json]               # List files
tvt cat <file>                # Stream file to stdout
tvt preview <file>            # Preview without full download
tvt find <query> [--json]     # Search files
tvt info <file> [--json]       # Detailed file info
tvt stat [--json]             # Vault statistics
tvt rm <file>                 # Delete file
tvt verify <file>             # Verify integrity
tvt gc [--dry-run]            # Garbage collection
tvt whoami                    # Show account info
tvt login                     # Authenticate
tvt setup                     # Configure channel (interactive)
tvt channel                   # Show channel info
tvt tui                       # Launch terminal UI (beta)

Pipeable I/O

echo "hello" | tvt push - --name note.txt
cat config.json | tvt push - --name config.json
mysqldump mydb | tvt push - --name backup.sql

tvt cat config.json | jq '.database'
tvt ls --json | jq '.[].name'
tvt find "backup" --json | jq '.[].size'

Backup & Restore

tvt backup create /data --name daily
tvt backup create /data --name incr --incremental
tvt backup list
tvt backup restore <id> --output /restore
tvt backup prune --keep-daily 7 --keep-weekly 4
tvt backup verify <id>

Virtual Drive

# FUSE mount with on-demand streaming
tvt mount -m ~/televault-drive

# WebDAV server
tvt serve --host 0.0.0.0 --port 8080

Auto-Backup

tvt schedule create /data --name daily --interval daily
tvt schedule install daily     # systemd timer (Linux)
tvt schedule list
tvt watch --path /data        # Watch for changes

---

Security

Your Machine                              Telegram Servers
─────────────                             ────────────────
Original File
     │
     v
┌──────────────┐
│  BLAKE3 Hash │  ◄── Chunk integrity
├──────────────┤
│ zstd Compress│  ◄── Optional, skips incompressible files
├──────────────┤
│ AES-256-GCM  │  ◄── scrypt-derived key, per-chunk salt+nonce
├──────────────┤     44 bytes overhead per chunk
│  BLAKE3 Hash │  ◄── Ciphertext integrity
├──────────────┤
└──────────────┘
     │
     v
  Encrypted chunks sent via MTProto
     │
     v
  Telegram only sees encrypted blobs

Your password never leaves your machine. Telegram servers see only encrypted data and JSON metadata references.

If you lose your password with encryption enabled, there is no recovery.

---

Data Safety

• Retry logic — All operations retry 3x with exponential backoff + FloodWait handling
• Sequential index access — asyncio.Lock prevents concurrent uploads from overwriting each other
• Atomic config writes — Temp file + os.replace + fsync prevents corruption on crash
• Upload cleanup — Failed uploads automatically delete orphaned messages
• Hash verification — Every chunk verified with BLAKE3 on download
• Original hash — Separate pre-encryption hash catches wrong-password errors
• Progress integrity — CRC32 checksums on resume files detect corruption; partial files preserved on failure
• Crash-safe stream — Single index save with correct filename, no double-save window
• Cached index lookups — O(1) message ID fetch prevents data loss from index scans
• Garbage collection — Dry-run by default, pinned messages always protected

---

Configuration

Config: ~/.config/televault/config.json

{
  "channel_id": -1003652003243,
  "index_msg_id": 42,
  "snapshot_index_msg_id": 150,
  "chunk_size": 104857600,
  "compression": true,
  "encryption": true,
  "parallel_uploads": 3,
  "parallel_downloads": 5,
  "max_retries": 3,
  "retry_delay": 1.0
}

Credentials: ~/.config/televault/telegram.json (or env vars TELEGRAM_API_ID / TELEGRAM_API_HASH)

Log: ~/.local/share/televault/televault.log

---

Project Structure

src/televault/
├── __init__.py        # Version
├── cli.py             # Click CLI — command dispatch, friendly errors
├── core.py            # TeleVault class — upload, download, list, search, stream
├── telegram.py        # TelegramVault — MTProto client, channel ops, index
├── models.py          # FileMetadata, ChunkInfo, VaultIndex, TransferProgress
├── chunker.py         # File splitting/merging, ChunkWriter, BLAKE3
├── crypto.py          # AES-256-GCM, scrypt KDF, streaming encrypt/decrypt
├── compress.py        # zstd compression, extension-based skip
├── config.py          # Config dataclass, atomic persistence, directory resolution
├── retry.py           # Exponential backoff, FloodWait handling
├── backup.py          # BackupEngine — snapshot CRUD, prune, verify
├── snapshot.py        # Snapshot, SnapshotFile, SnapshotIndex, RetentionPolicy
├── fuse.py            # TeleVaultFuse — on-demand streaming with LRU cache
├── webdav.py          # WebDAV server (aiohttp)
├── preview.py         # PreviewEngine — terminal previews from headers
├── watcher.py         # FileWatcher — polling, BLAKE2, exclude patterns
├── schedule.py        # Schedule CRUD, systemd timers, cron generation
├── gc.py              # Orphan message detection and cleanup
├── logging.py         # RotatingFileHandler setup
└── tui.py             # Textual TUI — file browser, detail panel

tests/
├── test_chunker.py
├── test_compress.py
├── test_crypto.py
├── test_fuse.py
├── test_models.py
├── test_models_v2.py
├── test_preview.py
├── test_retry.py
├── test_schedule.py
├── test_snapshot.py
├── test_telegram_helpers.py
└── test_webdav.py

See ARCHITECTURE.md for detailed system design.

---

Contributing

Contributions are welcome! Here's how to get started:

1. Fork the repository
2. Create a branch: git checkout -b feature/my-feature
3. Install dev dependencies: pip install -e ".[dev,fuse,webdav,preview]"
4. Run tests: pytest tests/ -v
5. Lint: ruff check src/
6. Commit with clear messages
7. Open a Pull Request

Development Setup

git clone https://github.com/YahyaToubali/televault.git
cd televault
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,fuse,webdav,preview]"
pytest                          # Run tests
ruff check src/                  # Lint

Key Concepts for Contributors

• Channel architecture: All data lives in a private Telegram channel as pinned index messages + reply chains. See ARCHITECTURE.md.
• Encryption pipeline: Files are chunked → hashed → compressed → encrypted → uploaded. The reverse on download. Each chunk has its own salt+nonce.
• Index system: VaultIndex maps file IDs to message IDs. Version-gated with 3 retries on API errors. Cached index msg IDs for O(1) lookup.
• Concurrency: asyncio.Lock serializes all index read-modify-write operations.
• Error handling: All CLI errors go through run_async() which catches exceptions and shows friendly messages. No Python tracebacks leak to users.
• Entry points: tvt and televault both resolve to televault.cli:main.

---

License

MIT License — See LICENSE for details.

Author: Yahya Toubali · @yahyatoubali