BucketSpace

Open-source, client-side encrypted personal cloud storage engine backed by Telegram MTProto.

Overview

BucketSpace turns your private Telegram storage into an unlimited, high-performance personal cloud drive.

Files are sliced and encrypted directly in your browser using standard AES-256-GCM before any data touches the network. Your master encryption key stays exclusively on your local device. The backend operates purely as an ephemeral MTProto relay, ensuring zero backend database lock-in and zero plaintext exposure.

Zero-Subscription Storage: Uses your existing Telegram account as a resilient, free cloud storage layer.
Client-Side Encryption: 256-bit AES-GCM encryption with unique random IVs per chunk executed via the Web Crypto API.
Adaptive 16 MB Chunking: Multi-part streaming with deterministic reassembly and SHA-256 integrity verification.
Stateless Backend: The Node.js server stores no database records, no user files, and no persistent credentials.
Modern Private Drive Interface: Responsive file explorer, categorized navigation, search, share links, and procedural animated cloud aesthetics.

Architecture & Data Flow

BucketSpace separates stateless frontend client encryption from long-running Telegram MTProto socket operations:

┌────────────────────────────────────────────────────────────────────────────────────────┐
│                              1. CLIENT BROWSER (Vercel)                                │
│                                                                                        │
│   [ Selected File ] ──► [ 16 MB Chunk Slicing ] ──► [ Web Crypto AES-256-GCM ]         │
│                                                              │                         │
│   • Master Key stays strictly in localStorage                ▼                         │
│   • Random 12-byte IV per chunk                     Ciphertext Buffer                  │
│   • 128-bit integrity authentication tag            (Binary Payload)                   │
└───────────────────────────────────────────────┬────────────────────────────────────────┘
                                                │
                                                │ HTTPS POST /api/v1/telegram/mtproto/chunk
                                                │ Header: x-telegram-session
                                                ▼
┌────────────────────────────────────────────────────────────────────────────────────────┐
│                             2. BACKEND RELAY (Render)                                  │
│                                                                                        │
│   [ Validate Size (≤ 50 MB) ] ──► [ Connection Pool ] ──► [ GramJS 6-Worker Stream ]   │
│                                                              │                         │
│   • Zero backend database persistence                        ▼                         │
│   • Ephemeral session memory only                   MTProto 2.0 Encrypted              │
│   • Slices chunk into 512 KB physical parts         TCP Socket Stream                  │
└───────────────────────────────────────────────┬────────────────────────────────────────┘
                                                │
                                                │ MTProto saveBigFilePart (Parallel Workers)
                                                ▼
┌────────────────────────────────────────────────────────────────────────────────────────┐
│                           3. STORAGE BACKBONE (Telegram)                               │
│                                                                                        │
│   [ Telegram Data Centers ] ──► [ #bucketspace-vault ] ──► [ Document Message ID ]    │
│                                                                                        │
│   • High-durability unlimited cloud storage                                            │
│   • Stored as encrypted documents in your private channel                              │
│   • Reconstructible anytime directly via your Telegram credentials                     │
└────────────────────────────────────────────────────────────────────────────────────────┘

End-to-End Pipeline

Stage	Execution Context	What Happens	Security & Privacy Guarantee
1. Slice & Hash	Browser	Slices file into 16 MB bounded chunks and calculates SHA-256 integrity hash.	Plaintext never leaves browser memory
2. Encrypt	Browser	Encrypts each chunk with AES-256-GCM using a unique 12-byte random IV.	Master key stays in `localStorage`
3. Relay	Render Backend	Streams binary ciphertext to Telegram via pooled GramJS MTProto workers.	Backend sees only encrypted bytes
4. Store	Telegram Cloud	Saved as document messages inside user's private `#bucketspace-vault` channel.	Telegram stores encrypted ciphertext
5. Download	Browser	Fetches encrypted chunks, validates SHA-256 hash, and decrypts with master key.	Bit-exact verification before save

Download & Reassembly Path:

Telegram Vault ──► Backend Relay (Encrypted Chunks) ──► Browser Decryption (AES-256-GCM) ──► Saved File

Key Features

Capability	Technical Implementation	Guarantee
Client Encryption	Web Crypto API `AES-256-GCM`	Backend & Telegram never see plaintext payloads
Chunking Engine	Bounded 16 MB logical chunks (configurable to 4 / 32 MB)	Bypasses HTTP payload limits & allows parallel parts
Integrity Checks	Deterministic SHA-256 digest per chunk and whole file	Bit-exact reassembly and tamper detection
Authentication	MTProto 2.0 SRP authentication with 2FA support	Ephemeral in-memory login; session string stored in browser
Public Sharing	Ephemeral token-based share routes (`/s/[token]`)	Optional constant-time passcodes and instant revocation
Zero Backend DB	Ephemeral memory cache with client-side persistence	No user database to maintain, breach, or backup

Installation & Setup

Choose your operating system for exact step-by-step setup instructions:

Step 1: Install on Your Platform

🐧 Linux (Ubuntu / Debian / Fedora / Arch)

Install Node.js 22 & pnpm:

# Ubuntu / Debian
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs git
sudo corepack enable && corepack prepare pnpm@latest --activate

# Arch Linux
sudo pacman -S nodejs npm git
sudo npm install -g pnpm

# Fedora
sudo dnf install -y nodejs npm git
sudo npm install -g pnpm

Clone & Install Dependencies:

git clone https://github.com/vanrajsinh650/BucketSpace.git
cd BucketSpace
pnpm install

Initialize Environment Config:
```
cp .env.example .env.local
```

🍏 Apple macOS (Apple Silicon M-Series & Intel)

Install via Homebrew:

# If Homebrew is not installed:
# /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install node@22 pnpm git

Clone & Install Dependencies:

git clone https://github.com/vanrajsinh650/BucketSpace.git
cd BucketSpace
pnpm install

Initialize Environment Config:
```
cp .env.example .env.local
```

🪟 Windows (PowerShell & WSL2)

Option A: Native Windows (PowerShell)

Install Node.js 22 & pnpm:

# Using Windows Package Manager (winget)
winget install OpenJS.NodeJS.LTS
winget install Git.Git

# Install pnpm globally
npm install -g pnpm

Tip: If you encounter PowerShell script execution restrictions with pnpm, run:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Clone & Install Dependencies:

git clone https://github.com/vanrajsinh650/BucketSpace.git
cd BucketSpace
pnpm install

Initialize Environment Config:
```
Copy-Item .env.example .env.local
```

Option B: WSL2 (Ubuntu on Windows - Recommended) Open your WSL terminal and follow the Linux (Ubuntu/Debian) instructions above.

Step 2: Obtain Telegram API Credentials

BucketSpace connects to Telegram using official MTProto 2.0 user credentials. To generate your API keys:

Log in with your Telegram account at https://my.telegram.org.
Click API development tools.
Fill in the required fields:
- App title: BucketSpace (or your preferred name)
- Short name: bucketspace
- Platform: Web or Desktop
Click Create application.
Copy your api_id (numeric) and api_hash (alphanumeric string).

Note

These credentials identify your application with Telegram's MTProto servers. They are kept securely on the backend and are never exposed to the browser.

Step 3: Configure Environment Variables

Copy the provided example environment file to .env.local:

cp .env.example .env.local

Open .env.local in your editor and enter your credentials:

# ============================================================
# BucketSpace — Local Configuration (.env.local)
# ============================================================

# Telegram MTProto API Credentials (from https://my.telegram.org)
TELEGRAM_API_ID="12345678"
TELEGRAM_API_HASH="0123456789abcdef0123456789abcdef"

# API URL (Leave blank for local development — browser uses same-origin)
NEXT_PUBLIC_API_URL=""

# Allowed CORS origins
CORS_ORIGINS="http://localhost:3000"

# Chunk upload socket timeout in milliseconds (default: 5 minutes)
UPLOAD_TIMEOUT_MS=300000

# Node Environment
NODE_ENV=development

Step 4: Start the Development Server

Run the development server:

pnpm dev

Open your browser and navigate to:

http://localhost:3000

Click Get Started or Connect to Telegram.
Enter your phone number (with country code, e.g. +1...).
Enter the verification code sent to your Telegram app.
If prompted, enter your Telegram 2FA cloud password.
Your private #bucketspace-vault channel is automatically initialized, and your encrypted drive is ready!

Step 5: Run Verification & Tests

BucketSpace comes with an automated unit test suite covering chunking, encryption, integrity hashing, MTProto auth, routing, and sharing:

# Run all 38 automated test suites
pnpm test

# Check TypeScript static types
pnpm type-check

# Compile production build
pnpm build

Production Deployment (Vercel + Render)

BucketSpace is optimized for a dual-host production topology:

Vercel: Serves the Next.js frontend, static assets, and client-side encryption.
Render: Runs the persistent Node.js service for Telegram MTProto socket connections.

Deploying the Backend to Render

Create a new Web Service in Render Dashboard.
Connect your BucketSpace repository.
Configure settings:
- Runtime: Node
- Branch: main
- Build Command: pnpm install && pnpm run build
- Start Command: pnpm run start
- Health Check Path: /api/health
Set Environment Variables in Render:
- TELEGRAM_API_ID: Your Telegram API ID
- TELEGRAM_API_HASH: Your Telegram API Hash
- CORS_ORIGINS: https://your-frontend.vercel.app
- NODE_ENV: production
Note your Render service URL (e.g. https://bucketspace-backend.onrender.com).

Deploying the Frontend to Vercel

Import the BucketSpace repository into Vercel.
Framework Preset: Next.js (auto-detected).
Set Environment Variables in Vercel:
- NEXT_PUBLIC_API_URL: https://bucketspace-backend.onrender.com (your Render URL)
Click Deploy.

For detailed deployment instructions and production configuration, see DEPLOYMENT.md.

Security Model

Client-Side Cryptography: File encryption uses standard AES-256-GCM with unique 12-byte initialization vectors generated via window.crypto.getRandomValues.
Key Isolation: Master encryption keys are stored exclusively in browser localStorage (bucketspace_master_encryption_key). Neither the backend relay nor Telegram servers receive the key.
No Database Footprint: The backend does not maintain a database of file catalogs, user passwords, or phone numbers. All file metadata resides on the user's client device.
Strict Session Scoping: The backend processes Telegram operations via per-request x-telegram-session headers with zero cross-tenant session sharing.
Origin-Enforced CORS: The backend rejects API requests from unauthorized web origins.

Detailed security documentation is available in the /context directory:

context/SECURITY_AUDIT.md — Cryptographic architecture and audit findings.
context/THREAT_MODEL.md — Threat modeling and security boundaries.
context/SECURITY_INVARIANTS.md — Enforced system invariants.

Repository Structure

BucketSpace/
├── src/
│   ├── app/                 # Next.js 15 App Router pages, layouts, and API routes
│   │   ├── api/v1/          # Telegram auth, MTProto chunk, vault, and share routes
│   │   ├── privacy/         # Dedicated /privacy disclosure route
│   │   ├── s/ & share/      # Public token share preview & download routes
│   │   ├── layout.tsx       # Root layout, fonts, and accessibility skip-link
│   │   └── page.tsx         # Main application entry point & onboarding gate
│   ├── components/          # Modular UI components (modals, file grid, clouds, sidebar)
│   ├── lib/                 # Storage store, Web Crypto SHA-256, error humanizer
│   ├── modules/
│   │   ├── security/        # Client-side AES-256-GCM encryption service
│   │   └── storage/         # Telegram MTProto adapter, connection pool & routing
│   ├── shared/              # Domain types, byte utilities, and chunk definitions
│   └── middleware.ts        # Production CORS origin validation middleware
├── tests/                   # 38 unit test suites (chunking, crypto, auth, shares)
├── context/                 # Architecture specifications, runbooks, and project state
├── LICENSE                  # Apache License 2.0
├── PRIVACY.md               # Technical Privacy Policy & data handling disclosures
├── DEPLOYMENT.md            # Production Vercel + Render deployment specification
└── package.json             # Pinned dependencies & runtime scripts

Privacy Policy & Legal

Open Source License: BucketSpace is released under the Apache License 2.0.
Privacy Disclosures: Our technical data handling practices are transparently documented in PRIVACY.md and accessible in-app at /privacy.
Notice: BucketSpace is an independent open-source project and is not affiliated with, sponsored by, or endorsed by Telegram FZ-LLC or Telegram Messenger Inc.

Author & Contact

Developed by Vanraj Solanki

Email: vanrajsolanki2875@gmail.com
GitHub: @vanrajsinh650

Name		Name	Last commit message	Last commit date
.agents		.agents
.github/workflows		.github/workflows
context		context
scripts		scripts
src		src
tests		tests
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
.npmrc		.npmrc
.nvmrc		.nvmrc
CLEANUP_REPORT.md		CLEANUP_REPORT.md
CODEBASE_CLEANUP_FINAL.md		CODEBASE_CLEANUP_FINAL.md
DEPLOYMENT.md		DEPLOYMENT.md
Dockerfile		Dockerfile
LICENSE		LICENSE
PRIVACY.md		PRIVACY.md
README.md		README.md
next-env.d.ts		next-env.d.ts
next.config.js		next.config.js
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
postcss.config.js		postcss.config.js
render.yaml		render.yaml
tailwind.config.js		tailwind.config.js
tsconfig.json		tsconfig.json

Navigation Menu

Repository files navigation

BucketSpace

Overview

Architecture & Data Flow

End-to-End Pipeline

Key Features

Installation & Setup

Step 1: Install on Your Platform

Step 2: Obtain Telegram API Credentials

Step 3: Configure Environment Variables

Step 4: Start the Development Server

Step 5: Run Verification & Tests

Production Deployment (Vercel + Render)

Deploying the Backend to Render

Deploying the Frontend to Vercel

Security Model

Repository Structure

Privacy Policy & Legal

Author & Contact

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

BucketSpace

Overview

Architecture & Data Flow

End-to-End Pipeline

Key Features

Installation & Setup

Step 1: Install on Your Platform

Step 2: Obtain Telegram API Credentials

Step 3: Configure Environment Variables

Step 4: Start the Development Server

Step 5: Run Verification & Tests

Production Deployment (Vercel + Render)

Deploying the Backend to Render

Deploying the Frontend to Vercel

Security Model

Repository Structure

Privacy Policy & Legal

Author & Contact

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages