# TG Drive Official Documentation **Version:** 3.5.0 Stable Release (Build 2700) **URL:** [https://tgdriveo.pages.dev/docs](https://tgdriveo.pages.dev/docs) **Live Application:** [https://tgdriveo.pages.dev/](https://tgdriveo.pages.dev/) **Android APK:** [Download Native APK](https://github.com/Saini920/DevKit-Manager-v4.0.7/releases/download/tg-drive-2.0.0/TG_Drive_2.0.0.apk) --- ## Table of Contents 1. [About TG Drive](#1-about-tg-drive) 2. [What's New in Version 3.5.0](#2-whats-new-in-version-350) 3. [Premium Features](#3-premium-features) 4. [Android Native App](#4-android-native-app) 5. [System Policies & Limits](#5-system-policies--limits) 6. [Setup Guide](#6-setup-guide) 7. [Storage System: Smart Hybrid Architecture](#7-storage-system-smart-hybrid-architecture) 8. [How It Works: Virtual File System (VFS)](#8-how-it-works-virtual-file-system-vfs) 9. [Storage Logic & Quota Breakdown](#9-storage-logic--quota-breakdown) 10. [Transfers Manager & Concurrency Queue](#10-transfers-manager--concurrency-queue) 11. [Real-Time Cloud Synchronization](#11-real-time-cloud-synchronization) 12. [Frequently Asked Questions (FAQ)](#12-frequently-asked-questions-faq) 13. [Secure Vault & Zero-Knowledge E2EE Architecture](#13-secure-vault--zero-knowledge-e2ee-architecture) 14. [Desktop Experience & Keyboard Shortcuts](#14-desktop-experience--keyboard-shortcuts) 15. [Privacy, Stealth Shield & Security](#15-privacy-stealth-shield--security) --- ## 1. About TG Drive TG Drive is a premium cloud storage interface designed to transform your Telegram experience into a professional file management system. It utilizes your personal Cloud Storage space to host and organize files of any type. By connecting directly to the official Telegram servers, the app ensures that your data is always available across all your devices without the typical subscription costs associated with traditional cloud providers. - **Direct MTProto 2.0:** All communication occurs directly between your client (browser or native app) and Telegram's data centers via GramJS MTProto 2.0. - **Zero Third-Party Storage:** No user files, tokens, or encryption keys are ever transmitted to or stored on TG Drive servers. - **Client-Side Virtual File System:** Folder hierarchies, tags, and file metadata are stored right inside your private Telegram Saved Messages. --- ## 2. What's New in Version 3.5.0 Version 3.5.0 (Build 2700) is the latest stable release featuring major cryptographic enhancements, disaster recovery protocols, and performance upgrades: - **Zero-Knowledge End-to-End Vault (E2EE):** Military-grade client-side encryption using AES-GCM 256-bit and PBKDF2 with 100,000 SHA-256 iterations. Credentials and files are encrypted before leaving your browser. - **Dual-Channel OTP Password Recovery:** User-selectable choice between personal Telegram Saved Messages (direct MTProto, 0% bot ban risk) and Telegram Bot for 6-digit recovery codes with session-preserving PIN reset. - **Automatic Multi-Device Cloud Sync:** Zero-touch background synchronization of cryptographic salt and canary tokens via Telegram Saved Messages (`#TG_DRIVE_VAULT_CONFIG#`) with real-time active status indicators across all devices. - **Android Native Biometric Unlock:** Native fingerprint and facial recognition integrated directly with the Android Hardware Keystore for lightning-fast, secure vault access on mobile. - **Responsive Modular Profile Interface:** Streamlined preferences, modular vault controls, and stealth blur protection. - **Background Legacy File Migration:** One-tap background engine to scan and encrypt older unencrypted files into the AES-256 vault, with optional Wi-Fi only restriction to preserve mobile data. - **Hardened Multi-Salt Session Recovery:** Dual-tier encrypted session storage in IndexedDB with automated fallback resolution across legacy salt structures, preventing accidental logouts. - **Smart Pause & Resume & SW Streaming:** High-speed MTProto streaming pipeline with chunk-level persistence, enabling pause, resume, and direct streaming to the browser's native download manager. --- ## 3. Premium Features - **Multipart Architecture:** Upload and download massive files efficiently by splitting them into safe, high-speed MTProto chunks (512 KB slices). - **Pause & Resume:** Interrupt and continue downloads seamlessly with chunk-level persistence, saving data and time on large transfers. - **Deep Nesting:** Unlimited folder depth with lightning-fast smart indexing stored directly in your Telegram cloud. - **Local Persistence:** Utilizes IndexedDB (`idb-keyval`) for high-speed local caching and instant app responsiveness. - **Zero Server Storage:** Pure peer-to-peer communication via GramJS MTProto. No middleman servers. - **Bank-Grade Privacy:** Leverages Telegram's native encryption and your personal API credentials for absolute security. --- ## 4. Android Native App TG Drive is available as a native Android application built with Capacitor: - **Direct APK Download:** `https://github.com/Saini920/DevKit-Manager-v4.0.7/releases/download/tg-drive-2.0.0/TG_Drive_2.0.0.apk` - **Native Performance:** Buttery-smooth transitions, zero browser address bar interference. - **Background Transfers:** Uploads and downloads continue reliably when minimized. - **Hardware Biometric Keystore:** Secure single-touch fingerprint and face authentication. - **Push Alerts:** Real-time native alerts for transfer completions and system events. - **Privacy Shield:** Independent stealth blur toggles for username, phone number, and thumbnails. --- ## 5. System Policies & Limits To ensure maximum stability and real-time performance across Telegram's MTProto API, TG Drive enforces clear system limits: - **Upload File Size Limit:** Strict 2.0 GB maximum file size policy per file (aligned with standard Telegram file size ceilings). - **Batch Uploading Limit:** Up to 100 files can be selected and queued at once in a single batch. - **Concurrent Download Limit:** Maximum of 3 simultaneous downloads. Additional files wait in a smart priority queue and start automatically as active transfers finish, preventing Telegram API `FLOOD_WAIT` rate limiting and browser memory exhaustion. --- ## 6. Setup Guide Connecting your Telegram account to TG Drive takes less than 2 minutes: 1. **Obtain API Credentials:** Visit [https://my.telegram.org](https://my.telegram.org), log in with your phone number, navigate to "API development tools", and create an application to obtain your `API ID` and `API Hash`. 2. **Create a Bot Token:** Message `@BotFather` on Telegram, create a new bot using `/newbot`, and copy the provided `Bot Token`. (Used for profile photos and optional OTP recovery). 3. **Authorize Account:** Open TG Drive, enter your phone number, API ID, API Hash, and Bot Token. Enter the official Telegram verification code sent to your Telegram app. 4. **Start Organizing:** Your Telegram "Saved Messages" chat is now your unlimited cloud drive! --- ## 7. Storage System: Smart Hybrid Architecture TG Drive uses a Smart Hybrid Storage engine optimizing for speed, privacy, and file size: - **MTProto Direct:** - Files up to 2.0 GB. - High Privacy (Direct P2P GramJS connection). - Encrypted chunks sent straight to your Telegram Saved Messages chat. - **Bot API Gateway:** - Fast metadata indexing and profile photo caching. - Fallback channel for small files (< 20 MB). - Secondary notification channel for OTP recovery codes. --- ## 8. How It Works: Virtual File System (VFS) TG Drive creates a Virtual File System (VFS) on top of Telegram Saved Messages by embedding structured JSON metadata tags: ```json // VFS Message Tagging Structure { "prefix": "#TG_DRIVE_FILE#", "meta": { "fileName": "Project_Archive.zip", "parentId": "root_vault", "totalSize": 2147483648, "isMultipart": true, "parts": 4, "encrypted": true } } ``` When you request a file, TG Drive fetches the corresponding MTProto message chunks, verifies cryptographic integrity, and streams the decrypted bytes directly to disk via a Service Worker. --- ## 9. Storage Logic & Quota Breakdown - **9999 TB Quota:** Visual representation reflecting Telegram's virtually unlimited Saved Messages capacity. - **Categorization Donut Chart:** - **Images:** JPG, PNG, GIF, WEBP, SVG, RAW. - **Videos:** MP4, MKV, MOV, AVI, WEBM. - **Apps & Zips:** ZIP, RAR, 7Z, TAR, GZ, APK, EXE, DMG. - **Documents:** PDF, DOCX, XLSX, PPTX, TXT, CSV, EPUB. - **Others:** Audio, code files, unknown formats. - **Critical Notice:** Never manually delete `#TG_DRIVE_FILE#` or `#TG_DRIVE_VAULT_CONFIG#` messages in your official Telegram "Saved Messages" chat, as this breaks cloud indexing. --- ## 10. Transfers Manager & Concurrency Queue - **Aggregate Progress Bar:** Sleek floating progress pill at the bottom of the viewport showing aggregate percentage, total transferred bytes, and active transfer count. - **Granular Transfers View:** Tabbed panels for "Uploaded" and "Downloaded" items with real-time speed (MB/s), ETA calculation, chunk-level progress, and pause/resume/cancel controls. - **100-File Batch Upload:** Queue entire folders or up to 100 individual files at once with automated chunk scheduling. - **3 Concurrent Transfers:** Strict 3-file concurrency queue prevents browser out-of-memory errors and Telegram network throttling. --- ## 11. Real-Time Cloud Synchronization - **MTProto Update Listeners:** Instant synchronization across all devices. Adding, renaming, moving, or deleting files triggers real-time indexing. - **Auto-Recovery:** TG Drive is completely stateless. Clearing your browser cache or switching devices requires only a login—all folders, files, and tags auto-recover within seconds. - **Favorites & Trash:** Full lifecycle virtual containers for starred files and soft-deleted items with instant restore capability (`Alt + R`). --- ## 12. Frequently Asked Questions (FAQ) ### Is TG Drive safe? Yes. TG Drive operates entirely client-side using official MTProto 2.0 protocols. Your API ID, API Hash, phone session strings, and Master PIN never touch any external server. ### What is the maximum file size? A strict limit of 2.0 GB per file is enforced for all uploads, adhering to Telegram's standard document size limit. ### Why do I need a Bot Token? The Bot Token acts as a lightweight metadata gateway for profile photos, fast thumbnail indexing, and optional OTP delivery without burdening your personal MTProto session. ### How does Master PIN / Password Recovery work? If you forget your 4-digit Master PIN: 1. Tap **Forgot Password** on the lock screen. 2. Select your delivery channel: - **Saved Messages (Recommended):** Directly to your Telegram Saved Messages via MTProto with **0% risk of bot bans**. - **Telegram Bot:** Delivered via your configured Bot Token. 3. Enter the 6-digit OTP code to verify and reset your PIN while **preserving your active Telegram login session**. ### How does Multi-Device Sync work? Multi-Device Sync is 100% automated and zero-touch. When you configure the Vault, TG Drive securely anchors your cryptographic salt and verification canary into a tagged message (`#TG_DRIVE_VAULT_CONFIG#`) in your Telegram Saved Messages. Secondary devices discover this config automatically upon login—entering your Master PIN unlocks the vault without manual import/export. ### What is the concurrent download and batch upload limit? Up to **100 files per upload batch** and **3 simultaneous concurrent downloads** to prevent Telegram `FLOOD_WAIT` rate limits. ### What is Privacy & Stealth Shield? Stealth Shield provides independent client-side frosted glass blur toggles for: - Telegram Username (`@username`) - Telegram Phone Number - Media Gallery & File Manager Thumbnails Hovering or tapping temporarily reveals blurred items. ### Does Privacy Shield affect file quality or download speed? No. Privacy Shield is a cosmetic CSS visual filter. Uploads, downloads, and stored files remain 100% full-resolution and uncompressed. ### How do Desktop Right-Click Menus and Drag-and-Drop work? Right-clicking any file card opens a desktop context menu (Download, Star, Rename, Info, Trash). Right-clicking blank space opens folder actions (Upload, New Folder, Select 100, Refresh). Dragging files into the window activates a frosted glass drop zone for instant batch uploading. ### How do I open the Keyboard Shortcuts Cheat Sheet? Press `?` (or `Shift + /`) anywhere in the application to open the interactive, searchable Keyboard Shortcuts modal. --- ## 13. Secure Vault & Zero-Knowledge E2EE Architecture ### Cryptographic Specifications | Parameter | Standard / Value | Security Benefit | | :--- | :--- | :--- | | **Cipher & Mode** | AES-256-GCM | Authenticated symmetric encryption with 128-bit authentication tags; prevents tampering and bit-flipping. | | **Key Derivation (KDF)** | PBKDF2-HMAC-SHA256 | NIST-approved key stretching resistant to GPU/ASIC rainbow table cracking. | | **KDF Iterations** | 100,000 Rounds | High computational workload preventing brute-force dictionary attacks against 4-digit PINs. | | **Entropy Salt** | 128 bits (16 bytes CSPRNG) | Unique per vault; generated via `crypto.getRandomValues`. Prevents pre-computed rainbow tables. | | **Initialization Vector (IV)** | 96 bits (12 bytes unique/chunk) | Unique IV per encrypted chunk; absolute zero-IV-reuse guarantee. | | **Authentication Tag** | 128 bits (16 bytes) | Validates cryptographic authenticity before ciphertext is decrypted. | | **Canary Token** | `TG_DRIVE_VAULT_TEST` | Instant PIN validation without risking state corruption or partial decryption. | | **Cloud Sync Anchor** | Telegram Saved Messages | Zero external database; config stored as `#TG_DRIVE_VAULT_CONFIG#`. | ### The 11 Cryptographic Lifecycle Phases 1. **Phase 1: Entropy & Salt Generation:** Generates a 16-byte cryptographically secure random salt using `crypto.getRandomValues(new Uint8Array(16))`. 2. **Phase 2: PBKDF2 Key Derivation:** Derives a non-extractable 256-bit AES-GCM `CryptoKey` from your Master PIN using PBKDF2-HMAC-SHA256 with 100,000 rounds. 3. **Phase 3: Canary Verification Token:** Encrypts `TG_DRIVE_VAULT_TEST` with a unique 12-byte IV. The ciphertext hex is stored in vault config to reliably verify PIN correctness. 4. **Phase 4: Session Credentials Hardening:** MTProto session string, API credentials, and bot tokens are encrypted with AES-256-GCM and stored in IndexedDB under `tg_vault_data`. Plain-text credentials are purged. 5. **Phase 5: Automatic Cloud Sync via Saved Messages:** Dispatches `#TG_DRIVE_VAULT_CONFIG#` to Telegram Saved Messages containing the salt, canary ciphertext, and timestamp. Master keys and PINs are NEVER sent. 6. **Phase 6: Zero-Touch Multi-Device Cross-Unlock:** Secondary devices discover `#TG_DRIVE_VAULT_CONFIG#` automatically. Entering your Master PIN derives the matching key and unlocks your vault with zero manual configuration. 7. **Phase 7: Filename Obfuscation & Envelope:** Files uploaded in High Security mode have their file names and MIME metadata encrypted into an envelope format (`enc__`). 8. **Phase 8: Streaming Chunk-Level Encryption & Decryption:** Files are split into 512 KB chunks, each encrypted with AES-GCM and its own tag. Downloads stream through the Service Worker directly to disk with RAM usage below 50 MB. 9. **Phase 9: Android Hardware Biometric Keystore:** Interfaces with Android BiometricPrompt and Secure Hardware Keystore for fingerprint and facial authentication. 10. **Phase 10: 12-Word BIP39 Root Seed & Disaster Recovery:** Standardized 12-word cryptographic seed allows instant derivation of the root master key and sets a fresh 4-digit PIN on any device without loss of encrypted data. 11. **Phase 11: Real-Time Session Termination Watchdog & Safe Logout Safeguard:** If a session is terminated remotely from Telegram Devices, TG Drive preserves your 12-word recovery phrase in local memory and triggers the safeguard modal upon app launch. Final logout requires explicit confirmation after viewing/copying/downloading the 12 words as a `.txt` file. ### Architectural Deep Dives #### Multi-Device Sync Without Central Servers TG Drive uses your personal Telegram Saved Messages as a secure, decentralized state anchor. The `#TG_DRIVE_VAULT_CONFIG#` message stores only the public 16-byte salt and encrypted canary token. When you enter your PIN on a phone, laptop, or tablet, the client validates the canary and derives the master key locally. #### Strict Device-Specific Lock (Option A) & Envelope Encryption - **Hardware-Bound PIN:** Each physical device is bound to its own unique salt and device slot in `config.deviceSlots` via `BOUND_DEVICE_SALT_KEY`. - **PIN Isolation:** A PIN set on Device 1 will strictly fail on Device 2 with `"Incorrect Master Password or PIN"`, preventing unauthorized unlock across shared devices. - **Envelope Encryption Decryption:** Files are encrypted with a single master `sharedFileKey`. Each device slot holds an encrypted copy of this key, guaranteeing 100% seamless cross-device file decryption and synchronization. - **Forgot Password Resilience:** Resetting your PIN via the 12-word phrase on Device 1 updates only Device 1's slot and preserves all sibling device slots, so other devices never lose sync. #### Accidental Deletion of `#TG_DRIVE_VAULT_CONFIG#` (Real-Time Auto-Recovery) - Your encrypted files are NOT deleted or corrupted. The vault config message only stores public salts and canary tokens. - **Real-Time Auto-Heal Watchdog:** TG Drive's auto-recovery engine continuously monitors Telegram Saved Messages. If the `#TG_DRIVE_VAULT_CONFIG#` message is deleted, any active device with a local vault cache automatically re-publishes it back to Saved Messages within seconds (upon routine sync, MTProto deletion events, or window focus). - If all devices were logged out, entering your 12-word recovery phrase generates a fresh salt, re-derives the master key, sets a new PIN, and publishes a new config. #### Clearing Browser Cache or Reinstalling App - Wiping cookies or reinstalling the APK clears local cache, but all encrypted files and `#TG_DRIVE_VAULT_CONFIG#` remain safe in Telegram. - Log back in with your phone number and Telegram OTP. - TG Drive retrieves the config from Saved Messages, prompts for your 4-digit PIN, and unlocks all files immediately. #### Remote Telegram Session Termination Watchdog When Telegram invalidates a session (`AUTH_KEY_UNREGISTERED` or `SESSION_REVOKED`), TG Drive intercepts the event, stores your 12-word recovery phrase in a persistent emergency buffer (`tg_pending_revocation_phrase`), and displays the Session Safeguard Modal with Copy and Download as .TXT buttons. #### Concurrency Control (Device Slotting) Version 2 vault configuration supports independent device session slots (`deviceSlots`). Each client updates its own slot keyed by a unique device salt hash, while Telegram's monotonic 32-bit message IDs resolve race conditions deterministically. #### Stolen Phone Threat Modeling 1. Terminate the session immediately from any other device via Telegram: `Settings → Devices → Terminate Session`. 2. All offline session data in IndexedDB is encrypted with AES-256-GCM and requires your 4-digit PIN. 3. On Android devices, biometric keys are isolated inside the hardware Secure Enclave. 4. **Remote Slot Revocation:** Perform a password reset using your 12-word recovery phrase on another device to revoke and overwrite the stolen device's slot in the cloud config forever. #### 12-Word BIP39 Root Seed vs 4-Digit Master PIN | Attribute | 4-Digit Master PIN | 12-Word Recovery Phrase | | :--- | :--- | :--- | | **Purpose** | Daily quick unlocking on local device | Root master cryptographic seed | | **Entropy** | PBKDF2 (100k rounds) + 16-byte salt | 128-bit BIP39 dictionary | | **Portability** | Validated via cloud canary token | Universal: restores vault on any device | | **Resettability** | Reset anytime using 12-word phrase | Permanent root master key | #### 7-Tier Cache Purging on Logout 1. **Tier 1 - IndexedDB:** Clears `idb-keyval` session strings and decrypted vault tokens. 2. **Tier 2 - Dexie VFS DB:** Purges all indexed folder structures and file metadata records. 3. **Tier 3 - Browser Cache API:** Calls `caches.delete()` for thumbnail blobs and media streaming chunks. 4. **Tier 4 - In-Memory Caches:** Revokes blob URLs and clears MTProto message caches. 5. **Tier 5 - LocalStorage Reset:** Wipes profile, transfer, and account data (preserves theme preferences). 6. **Tier 6 - SessionStorage Purge:** Clears temporary browser tab state. 7. **Tier 7 - Android Biometric Keystore:** Destroys biometric enclave keys via Capacitor NativeBiometric. --- ## 14. Desktop Experience & Keyboard Shortcuts ### Desktop Context Menus & Drag-and-Drop - **File Card Context Menu:** Right-click any file card to Download, Star/Favorite, Rename, View File Info, or Move to Trash. - **Background Context Menu:** Right-click empty workspace to Upload Files, Create New Folder, Select 100 Items, or Refresh Data. - **Drag & Drop:** Drag files directly from your desktop into the browser. A frosted glass drop zone validates 100-file batches and 2.0 GB file limits. ### Keyboard Shortcuts Reference #### File & Folder Operations - `U` - Open Upload dialog (up to 100 files) - `N` - Create New Folder - `Del` - Move selected/hovered item to Trash - `F2` - Rename selected item - `F` - Toggle Favorite / Star - `Enter` - Open Download / Preview modal - `Alt + R` - Restore selected file(s) from Trash - `Ctrl + A` - Select 100 items in batch - `Esc` - Close active modals, menus, or clear selection #### Global Navigation & Controls - `?` (or `Shift + /`) - Open Keyboard Shortcuts Cheat Sheet Modal - `Ctrl + K` - Global Quick Search - `/` - Focus Search Bar - `1` - Navigate to Dashboard (Home) - `2` - Navigate to File Manager (All Files) - `3` - Navigate to Media Gallery - `4` - Navigate to Transfers Queue - `5` - Navigate to Settings & Vault - `6` - Navigate to Storage Details (`Alt + S`) - `7` - Navigate to Favourite Files (`Alt + F`) - `8` - Navigate to Trash / Bin (`Alt + T`) - `9` - Navigate to Recent Files - `R` - Refresh Telegram Cloud Data --- ## 15. Privacy, Stealth Shield & Security - **Zero Data Logging:** No analytics tracking your personal files, file names, or IP addresses. - **Pure Client-Side Architecture:** The application code is hosted on Cloudflare Pages as a static PWA. Direct MTProto communication ensures Telegram handles all transport encryption. - **Privacy & Stealth Shield:** - **Hide Username:** Blurs `@username` across Sidebar, Profile Drawer, Settings, and PIN lock screen. - **Blur Phone Number:** Blurs phone number with hover-to-reveal. - **Blur Media Thumbnails:** Blurs all image thumbnails across Gallery and File Manager for privacy in public spaces. - **Independent Toggles:** Each setting can be enabled or disabled independently in Profile Drawer or Settings.