Metadata-Version: 2.4
Name: televault
Version: 2.8.0
Summary: Unlimited cloud storage using Telegram MTProto. No local DB - everything on Telegram.
Project-URL: Homepage, https://github.com/YahyaToubali/televault
Project-URL: Repository, https://github.com/YahyaToubali/televault
Author-email: Yahya Toubali <contact@yahyatoubali.me>
License: MIT
License-File: LICENSE
Keywords: backup,cloud,mtproto,storage,telegram
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Archiving :: Backup
Requires-Python: >=3.11
Requires-Dist: aiofiles>=23.2.0
Requires-Dist: blake3>=0.4.0
Requires-Dist: click>=8.1.0
Requires-Dist: cryptography>=42.0.0
Requires-Dist: rich>=13.7.0
Requires-Dist: telethon>=1.36.0
Requires-Dist: textual>=0.47.0
Requires-Dist: zstandard>=0.22.0
Provides-Extra: dev
Requires-Dist: mypy>=1.8.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.2.0; extra == 'dev'
Provides-Extra: fuse
Requires-Dist: fusepy>=3.0.1; extra == 'fuse'
Provides-Extra: preview
Requires-Dist: pillow>=10.0.0; extra == 'preview'
Provides-Extra: webdav
Requires-Dist: aiohttp>=3.9.0; extra == 'webdav'
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://img.shields.io/badge/version-2.7.0-blue?style=flat-square" alt="version">
  <img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="license">
  <img src="https://img.shields.io/badge/python-3.11+-yellow?style=flat-square" alt="python">
  <img src="https://img.shields.io/pypi/v/televault?style=flat-square" alt="pypi">
  <img src="https://img.shields.io/badge/encryption-AES--256--GCM-red?style=flat-square" alt="encryption">
</p>

<h1 align="center">
  <pre style="font-size:2.5rem;font-weight:900;letter-spacing:-0.05em;margin:0;">
  ██╗░██████╗  
  ██║██╔════╝  
  ██║██║░░██╗  
  ██║██║░░██║  
  ██║╚█████╔╝  
  ╚═╝░╚════╝░  </pre>
  <br>
  Unlimited cloud storage via Telegram
</h1>

<p align="center">
  <strong>Encrypt → Chunk → Upload to your private Telegram channel.</strong><br>
  <strong>No servers. No limits. No trust required.</strong>
</p>

<p align="center">
  <a href="#installation"><code>pip install televault</code></a>
  <span>&nbsp;·&nbsp;</span>
  <a href="https://yahyatoubali.github.io/televault/">Docs</a>
  <span>&nbsp;·&nbsp;</span>
  <a href="#quick-start">Quick Start</a>
  <span>&nbsp;·&nbsp;</span>
  <a href="./ARCHITECTURE.md">Architecture</a>
</p>

---

## 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.
- **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** — Full interactive file browser with detail panel.
- **Piping** — `cat file | tvt push -`, `tvt cat file | jq`, `tvt ls --json`.
- **Shell completion** — Bash, zsh, fish, PowerShell.
- **Auto-backup** — Schedules, systemd timers, file watching.
- **Garbage collection** — Find and remove orphaned messages.

---

## Installation

```bash
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

```bash
# 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

# 10) Install shell completion
tvt completion bash >> ~/.bashrc
```

---

## Usage

### Core Commands

```bash
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
```

### Pipeable I/O

```bash
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

```bash
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

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

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

### Auto-Backup

```bash
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
- **Atomic index updates** — Version-based concurrency control prevents data races
- **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
- **Garbage collection** — Find and remove orphaned messages

---

## Configuration

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

```json
{
  "channel_id": -1003652003243,
  "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, 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
├── completion.py      # Shell completion (bash, zsh, fish, PowerShell)
├── 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, login

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_completion.py
└── test_webdav.py
```

See [ARCHITECTURE.md](./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

```bash
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](./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 optimistic concurrency (5 retries).
- **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](./LICENSE) for details.

**Author**: Yahya Toubali · [@yahyatoubali](https://github.com/YahyaToubali)
