@nightowne/tas-cli 2.0.0 → 2.3.0

package/README.md

@@ -1,183 +1,377 @@
-# Telegram as Storage
+<p align="center">
+  <img src="assets/demo.gif" alt="TAS — Telegram as Storage" width="640">
+</p>
+
+<h1 align="center">
+  📦 TAS — Telegram as Storage
+</h1>
 
-[![CI](https://github.com/ixchio/tas/actions/workflows/ci.yml/badge.svg)](https://github.com/ixchio/tas/actions/workflows/ci.yml)
-[![npm](https://img.shields.io/npm/v/@nightowne/tas-cli)](https://www.npmjs.com/package/@nightowne/tas-cli)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+<h3 align="center">
+  Turn Telegram into your personal encrypted cloud drive.<br>
+  Free forever. Zero-knowledge. No credit card. No limits.
+</h3>
 
 <p align="center">
-  <img src="assets/demo.gif" alt="Demo" width="600">
+  <a href="https://github.com/ixchio/tas/actions/workflows/ci.yml"><img src="https://github.com/ixchio/tas/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://www.npmjs.com/package/@nightowne/tas-cli"><img src="https://img.shields.io/npm/v/@nightowne/tas-cli?color=cb3837&label=npm" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/@nightowne/tas-cli"><img src="https://img.shields.io/npm/dm/@nightowne/tas-cli?color=blue" alt="Downloads"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License: MIT"></a>
+  <a href="https://github.com/ixchio/tas/stargazers"><img src="https://img.shields.io/github/stars/ixchio/tas?style=social" alt="GitHub Stars"></a>
 </p>
 
-A CLI tool that uses your Telegram bot as encrypted file storage. Files are compressed, encrypted locally, then uploaded to your private bot chat.
+<p align="center">
+  <a href="#-quick-start">Quick Start</a> •
+  <a href="#-why-tas">Why TAS</a> •
+  <a href="#-features">Features</a> •
+  <a href="#%EF%B8%8F-security">Security</a> •
+  <a href="#-cli-reference">Docs</a> •
+  <a href="#-contributing">Contributing</a>
+</p>
 
-```
-┌─────────────┐     ┌───────────────┐     ┌──────────────┐
-│   CLI       │────▶│  Compress &   │────▶│  Telegram    │
-│   FUSE      │     │  Encrypt      │     │  Bot API     │
-└─────────────┘     └───────────────┘     └──────────────┘
-       │                    │                     │
-       ▼                    ▼                     ▼
-┌─────────────┐     ┌───────────────┐     ┌──────────────┐
-│ SQLite Index│     │ 49MB Chunks   │     │ Private Chat │
-└─────────────┘     └───────────────┘     └──────────────┘
-```
+---
 
-## Why TAS?
+<br>
 
-| Feature | TAS | Session-based tools (e.g. teldrive) |
-|---------|:---:|:-----------------------------------:|
-| Account ban risk | None (Bot API) | High (session hijack detection) |
-| Encryption | AES-256-GCM | Usually none |
-| Dependencies | SQLite only | Rclone, external DB |
-| Setup complexity | 2 minutes | Docker + multiple services |
+## The Problem
 
-Key differences:
-- Uses Bot API, not session-based auth - Telegram can't ban your account
-- Encryption by default - files encrypted before leaving your machine
-- Local-first - SQLite index, no cloud dependencies
-- FUSE mount - use Telegram like a folder
+Google Drive scans your files. Dropbox costs $12/mo. iCloud locks you into Apple. Every "free" cloud storage either **reads your data**, **charges you money**, or **caps your storage**.
 
-## Security Model
+Meanwhile, Telegram gives every user **unlimited storage** with a bot API — and nobody's using it.
 
-| Component | Implementation |
-|-----------|----------------|
-| Cipher | AES-256-GCM |
-| Key derivation | PBKDF2-SHA512, 100,000 iterations |
-| Salt | 32 bytes, random per file |
-| IV | 12 bytes, random per file |
-| Auth tag | 16 bytes (integrity) |
+## The Solution
 
-Your password never leaves your machine. Telegram stores encrypted blobs.
+**TAS** compresses, encrypts, and uploads your files to your own private Telegram bot chat. Your password never leaves your machine. Telegram only sees encrypted noise. You get a real CLI-powered cloud drive — with mount, sync, share, and search — for **$0/month, forever.**
 
-## Limitations
+```
+  Your Machine                          Telegram Cloud
+┌──────────────────┐               ┌──────────────────────┐
+│                  │   Compress    │                      │
+│   tas push       │──→ Encrypt ──→│  🔒 Encrypted Blobs  │
+│   tas mount      │──→ Chunk   ──→│  🔒 Private Bot Chat │
+│   tas sync       │               │  🔒 Your Data, Safe  │
+│                  │   Decrypt    │                      │
+│   tas pull       │←── Decomp ←──│  ← Download on demand│
+│                  │               │                      │
+└──────────────────┘               └──────────────────────┘
+     SQLite Index                     Unlimited & Free
+```
 
-- Not a backup - Telegram can delete content without notice
-- No versioning - overwriting a file deletes the old version
-- 49MB chunks - files split due to Bot API limits
-- FUSE required - mount feature needs libfuse on Linux/macOS
-- Single user - designed for personal use, not multi-tenant
+<br>
 
-## Quick Start
+## ⚡ Quick Start
+
+Three commands. Two minutes. Zero cost.
 
 ```bash
-# Install
 npm install -g @nightowne/tas-cli
 
-# Setup (creates bot connection + encryption password)
-tas init
+tas init              # Connect your Telegram bot (guided wizard)
+tas push secret.pdf   # Upload — encrypted, compressed, done
+tas pull secret.pdf   # Download — decrypted, verified, instant
+```
+
+That's it. You now have encrypted cloud storage.
+
+<br>
+
+## 💡 Why TAS
+
+<table>
+<tr>
+<td width="50%">
+
+### vs. Google Drive
+- ❌ Google scans & indexes your files
+- ❌ 15 GB free tier
+- ❌ No encryption at rest (by you)
+
+### vs. Dropbox
+- ❌ $12/mo for 2 TB
+- ❌ Can access your data
+- ❌ No CLI-first experience
+
+### vs. Mega / pCloud
+- ❌ Freemium with tight caps
+- ❌ Closed source encryption
+- ❌ Can't self-host or script
+
+</td>
+<td width="50%">
+
+### TAS gives you
+- ✅ **$0/month** — forever, no caps
+- ✅ **Zero-knowledge** — only you can decrypt
+- ✅ **AES-256-GCM** — military-grade encryption
+- ✅ **Mount as folder** — FUSE filesystem
+- ✅ **Auto-sync** — Dropbox-style folder sync
+- ✅ **Share links** — expiring, download-limited
+- ✅ **CLI-first** — cron, Docker, CI/CD ready
+- ✅ **Open source** — audit every line
+
+</td>
+</tr>
+</table>
+
+<br>
 
-# Upload a file
-tas push secret.pdf
+## 🔥 Features
 
-# Download a file
-tas pull secret.pdf
+### 🗂️ Mount as a Local Folder
+Drag and drop files into Telegram storage like it's a regular drive.
 
-# Mount as folder (requires libfuse)
-tas mount ~/cloud
+```bash
+tas mount ~/cloud        # Mount your Telegram storage
+# Now use Finder, Explorer, or any app — files sync to Telegram
+tas unmount ~/cloud
 ```
 
-### Prerequisites
-- Node.js ≥18
-- Telegram account + bot token from [@BotFather](https://t.me/BotFather)
-- `libfuse` for mount feature:
-  ```bash
-  # Debian/Ubuntu
-  sudo apt install fuse libfuse-dev
-  
-  # Fedora
-  sudo dnf install fuse fuse-devel
-  
-  # macOS
-  brew install macfuse
-  ```
+> Requires `libfuse` — `apt install fuse libfuse-dev` on Linux, `brew install macfuse` on macOS.
 
-## CLI Reference
+### 🔄 Auto-Sync Folders
+Dropbox-style: register a folder, and TAS watches for changes and uploads automatically.
 
 ```bash
-# Core
-tas init                    # Setup wizard
-tas push <file>             # Upload file
-tas pull <file|hash>        # Download file
-tas list [-l]               # List files (long format)
-tas delete <file|hash>      # Remove file
-tas status                  # Show stats
-
-# Search & Resume (v1.1.0)
-tas search <query>          # Search by filename
-tas search -t <query>       # Search by tag
-tas resume                  # Resume interrupted uploads
-
-# FUSE Mount
-tas mount <path>            # Mount as folder
-tas unmount <path>          # Unmount
+tas sync add ~/Documents    # Register a folder
+tas sync start              # Watch & auto-upload changes
+tas sync pull               # Download everything back
+tas sync status             # See what's synced
+```
 
-# Tags
-tas tag add <file> <tags...>    # Add tags
-tas tag remove <file> <tags...> # Remove tags
-tas tag list [tag]              # List tags or files by tag
+### 🔗 Share with Expiring Links
+Generate one-time download links with a sleek dark-themed download page. Files are decrypted on-the-fly — the link holder never sees your password.
 
-# Sync (Dropbox-style)
-tas sync add <folder>       # Register folder for sync
-tas sync start              # Start watching
-tas sync pull               # Download all to sync folders
-tas sync status             # Show sync status
+```bash
+tas share create report.pdf --expire 1h --max-downloads 3
+# → http://localhost:3000/d/a1b2c3d4...
 
-# Share (temporary links)
-tas share create <file>     # Create download link
-tas share create <file> --expire 1h --max-downloads 3
-tas share list              # Show active shares
-tas share revoke <token>    # Revoke a share
+tas share list              # See active shares
+tas share revoke a1b2c3d4   # Revoke anytime
+```
 
-# Verification
-tas verify                  # Check file integrity
+### 🏷️ Tags & Search
+Organize and find files instantly.
+
+```bash
+tas tag add report.pdf work Q4
+tas search "report"          # Search by filename
+tas search -t work           # Search by tag
 ```
 
-## Automation
+### 🩺 Self-Diagnostics
+One command to check if everything is healthy.
+
+```bash
+tas doctor
+# ✓ Node.js 20.11.0
+# ✓ Config v2 (encrypted token)
+# ✓ Database: 42 files, 1.3 GB total
+# ✓ Disk space: 50 GB free (32% used)
+# ✓ Encryption: AES-256-GCM, PBKDF2-SHA512 600,000 iterations
+# ✨ All systems go!
+```
 
-Skip password prompts for scripts and CI/CD:
+### 🤖 Built for Automation
+First-class JSON output, environment variable support, and zero interactivity mode.
 
 ```bash
-# Environment variable
-export TAS_PASSWORD="your-password"
-tas push file.pdf
-tas sync start
+export TAS_PASSWORD="your-password"     # Skip prompts
+export TAS_DATA_DIR="/custom/path"      # Custom data location
+
+tas push backup.tar.gz                  # Non-interactive upload
+tas list --json | jq '.[].filename'     # Pipe to jq
+tas status --json                       # Machine-readable status
+
+# Works with: cron • GitHub Actions • Docker • systemd • any CI/CD
+```
+
+<br>
+
+## 🛡️ Security
+
+TAS implements **zero-knowledge encryption** — we can't read your data, Telegram can't read your data, nobody can read your data without your password.
+
+| Layer | Implementation | Why It Matters |
+|-------|----------------|----------------|
+| **Cipher** | AES-256-GCM | Same cipher used by governments & banks |
+| **Key Derivation** | PBKDF2-SHA512, **600k iterations** | OWASP 2025 compliant — brute-force resistant |
+| **Salt** | 32 bytes, cryptographically random | Unique per file — no rainbow tables |
+| **IV** | 12 bytes, cryptographically random | Unique per file — no pattern analysis |
+| **Auth Tag** | 16 bytes GCM authentication | Tamper detection — any bit flip = rejected |
+| **Bot Token** | Encrypted at rest (AES-256-GCM) | Even your config file is protected |
+| **Password Hash** | PBKDF2-based verification | Your password hash is computationally expensive to crack |
+| **Integrity** | SHA-256 verified on every download | Bit-perfect downloads, guaranteed |
+| **Share Server** | XSS-safe, RFC 6266 headers | Hardened against injection attacks |
+
+For the full threat model, cipher rationale, and file format spec, see **[docs/security.md](docs/security.md)**.
+
+### What Telegram Sees
+
+```
+📦 a7f3b2c1e9d4.tas — 12.4 MB — application/octet-stream
+```
+
+That's it. An opaque encrypted blob. No filename, no content, no metadata. Just noise.
+
+<br>
+
+## 🔄 Reliability
+
+Built like professional backup tools (inspired by restic, rclone, borg):
+
+| Feature | Details |
+|---------|---------|
+| **Exponential Backoff** | Auto-retry with jitter on Telegram 429 errors and network timeouts |
+| **Rate Limiting** | Built-in 1 msg/sec limiter — never hits Telegram's rate limits |
+| **Integrity Verification** | SHA-256 hash check after every single download |
+| **Resume Uploads** | Interrupted? Run `tas resume` to pick up where you left off |
+| **Atomic Transactions** | Upload pipeline uses SQLite transactions — pipeline failure = clean rollback, zero orphaned DB rows |
+| **Graceful Shutdown** | SIGINT/SIGTERM handled cleanly — zero data corruption risk |
+| **Self-Diagnostics** | `tas doctor` validates your entire setup in seconds |
 
-# Or use CLI flag (recommended for CI/CD)
-tas push -p "password" file.pdf
+<br>
+
+## 📋 CLI Reference
+
+<details>
+<summary><strong>Core Commands</strong></summary>
+
+```bash
+tas init                    # 🚀 Interactive setup wizard
+tas push <file>             # ⬆️  Upload (encrypt + compress + upload)
+tas pull <file|hash>        # ⬇️  Download (download + decrypt + verify)
+tas list [-l] [--json]      # 📋 List all files
+tas delete <file|hash>      # 🗑️  Remove from index (--hard to delete from Telegram)
+tas status [--json]         # 📊 Storage stats
+tas search <query>          # 🔍 Find files by name or tag
+tas resume                  # 🔄 Resume interrupted uploads
+tas verify                  # ✅ Verify all files exist & are intact
+tas doctor                  # 🩺 System health check
 ```
 
-Works great with:
-- Cron jobs for automated backups
-- GitHub Actions and GitLab CI
-- Docker containers
-- Shell scripts for batch operations
+</details>
+
+<details>
+<summary><strong>Mount & Sync</strong></summary>
 
-## Auto-Start (systemd)
+```bash
+# FUSE Mount (use Telegram like a local folder)
+tas mount <path>            # Mount
+tas unmount <path>          # Unmount
+
+# Folder Sync (Dropbox-style auto-upload)
+tas sync add <folder>       # Register a folder to sync
+tas sync start              # Start watching for changes
+tas sync pull               # Download all synced files
+tas sync status             # Show sync status
+```
 
-See [systemd/README.md](systemd/README.md) for running sync as a service.
+</details>
 
-## Development
+<details>
+<summary><strong>Share & Tags</strong></summary>
 
 ```bash
-git clone https://github.com/ixchio/tas
-cd tas
-npm install
-npm test  # 28 tests
+# Temporary Share Links
+tas share create <file> [--expire 24h] [--max-downloads 3]
+tas share list              # Active shares
+tas share revoke <token>    # Revoke a share link
+
+# File Tags
+tas tag add <file> <tags...>
+tas tag remove <file> <tags...>
+tas tag list [tag]          # List tags or files with a specific tag
 ```
 
-### Project Structure
+</details>
+
+<br>
+
+## 🏗️ Architecture
+
 ```
 src/
-├── cli.js           # Command definitions
-├── index.js         # Upload/download pipeline
-├── crypto/          # AES-256-GCM encryption
-├── db/              # SQLite file index
-├── fuse/            # FUSE filesystem mount
-├── sync/            # Folder sync engine
-├── telegram/        # Bot API client
-└── utils/           # Compression, chunking
+├── cli.js              # Commander-based CLI — all commands
+├── index.js            # Streaming upload/download pipeline
+├── crypto/
+│   └── encryption.js   # AES-256-GCM + PBKDF2-SHA512 key derivation
+├── db/
+│   └── index.js        # SQLite index (files, chunks, tags, shares, sync)
+├── telegram/
+│   └── client.js       # Bot API wrapper — retry, rate-limit, streaming
+├── fuse/
+│   └── mount.js        # FUSE filesystem — mount Telegram as a folder
+├── share/
+│   └── server.js       # HTTP server — expiring download links
+├── sync/
+│   └── sync.js         # Folder watcher — Dropbox-style auto-sync
+└── utils/
+    ├── compression.js   # Smart gzip (skips already-compressed formats)
+    ├── chunker.js       # 49MB chunking with custom WAS1 file headers
+    ├── progress.js      # Terminal progress bar with speed + ETA
+    ├── throttle.js      # Bandwidth limiter (stream transform)
+    ├── branding.js      # ASCII art + version (auto-synced from package.json)
+    └── cli-helpers.js   # Password management + config resolution
+```
+
+**Tech stack:** Node.js · better-sqlite3 · node-telegram-bot-api · fuse-native · Commander · Chalk · Ora · Inquirer
+
+<br>
+
+## ⚠️ Good to Know
+
+| | |
+|---|---|
+| 📌 **Not a backup solution** | Telegram can delete content. Use TAS alongside proper backups, not instead of them. |
+| 📌 **49 MB chunks** | Files are automatically split due to Telegram Bot API limits. Fully transparent. |
+| 📌 **Single-user** | Designed for personal use. Not multi-tenant. |
+| 📌 **FUSE = Linux/macOS** | Mount feature requires `libfuse`. CLI works everywhere Node.js runs. |
+| 📌 **No versioning (yet)** | Overwriting a file replaces the previous version. |
+
+<br>
+
+## 🛠️ Development
+
+```bash
+git clone https://github.com/ixchio/tas
+cd tas && npm install
+npm test  # 83 tests across 16 suites, all passing
 ```
 
-## License
+For the full developer guide (architecture, testing, conventions, gotchas), see **[docs/development.md](docs/development.md)**.
+
+PRs welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+<br>
+
+## 📚 Documentation
 
-MIT
+| Doc | What's in it |
+|-----|-------------|
+| [docs/development.md](docs/development.md) | Developer onboarding — project structure, how to add commands, testing, conventions |
+| [docs/security.md](docs/security.md) | Threat model — what TAS protects against, cipher details, file format specs |
+| [CHANGELOG.md](CHANGELOG.md) | Version history with all changes documented |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | How to contribute — fork, branch, PR |
+| [SECURITY.md](SECURITY.md) | Security vulnerability reporting |
+
+<br>
+
+## 🌟 Contributing
+
+TAS is open source and we love contributions:
+
+- 🐛 **Found a bug?** [Open an issue](https://github.com/ixchio/tas/issues)
+- 💡 **Have an idea?** [Start a discussion](https://github.com/ixchio/tas/issues)
+- 🔧 **Want to contribute?** Fork → Branch → PR → 🎉
+
+<br>
+
+## 📄 License
+
+MIT — use it, fork it, ship it, sell it. Do whatever you want.
+
+---
+
+<p align="center">
+  <sub>Built with ☕ and stubbornness by <a href="https://github.com/ixchio">@ixchio</a></sub><br>
+  <sub>If TAS saved you money, consider giving it a ⭐</sub>
+</p>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nightowne/tas-cli",
-  "version": "2.0.0",
+  "version": "2.3.0",
   "description": "Telegram as Storage - Automated encrypted cloud backup. Free, encrypted, scriptable. Mount as folder or use with cron/Docker.",
   "type": "module",
   "main": "src/index.js",
@@ -46,11 +46,13 @@
     "better-sqlite3": "^12.6.2",
     "chalk": "^5.3.0",
     "commander": "^12.1.0",
-    "fuse-native": "^2.2.6",
     "inquirer": "^12.2.0",
     "node-telegram-bot-api": "^0.66.0",
     "ora": "^8.1.1"
   },
+  "optionalDependencies": {
+    "fuse-native": "^2.2.6"
+  },
   "engines": {
     "node": ">=18.0.0"
   }