FileHashVaultBot

Telegram bot that instantly hashes uploaded files (MD5 / SHA1 / SHA256 / SHA512) and keeps a 5-day temporary share vault using only Telegram file_id + SQLite — no permanent file storage on disk.

Optimized for Railway.app free tier (worker process, SQLite file, no external DB).

Features

• Instant streaming hashes on upload (8 MB chunks, no full-file RAM load)
• Unique 6-character share codes (A7K9P2 style; no O/0/I/1)
• Temporary vault: metadata + file_id only in vault.db
• Retrieve via /get CODE, plain code message, or deep link t.me/<bot>?start=CODE
• Inline actions: copy SHA256, share link, delete (uploader-only delete)
• Flood control: max 5 files / minute / user
• Persian UX messages
• Hourly expired-row cleanup job

Project layout

FileHashVaultBot/
├── bot.py              # Main async bot (python-telegram-bot v21)
├── database.py         # SQLite vault helpers
├── hash_utils.py       # Streaming hash + share-code helpers
├── requirements.txt
├── Procfile            # Railway worker process
├── railway.json
├── .env.example
├── .gitignore
└── README.md

Requirements

• Python 3.10+
• A Telegram bot token from @BotFather

Local run

cd FileHashVaultBot
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt

cp .env.example .env
# edit .env and set BOT_TOKEN=...

python bot.py

Environment variables

Variable	Required	Description
BOT_TOKEN	Yes	Telegram bot token
ADMIN_ID	No	Your numeric Telegram user id (enables /stats)
DATABASE_PATH	No	SQLite path (default: ./vault.db)
LOG_LEVEL	No	INFO (default), DEBUG, ...

Commands

Command	Description
/start	Welcome text; also handles deep-link retrieval
/help	Help
/get CODE	Fetch file by share code
/hash	Reply to a file message → hashes only (no vault)
/myfiles	Last 10 of your vault entries
/clearme	Delete all of your vault rows
/stats	Admin health check (if ADMIN_ID set)

Sending any document / video / photo / audio / voice / animation / sticker stores it in the vault automatically.

How storage works

1. User uploads a file to the bot.
2. Bot streams the file from Telegram only to compute hashes (never keeps a permanent copy).
3. Bot stores in SQLite: file_id, name, size, hashes, uploader id, timestamps, share code.
4. Anyone with the code can ask the bot to re-send the file via file_id.
5. After 5 days the DB row is purged (hourly job + on-access cleanup).

Important Telegram Bot API limit: bots can download files for hashing up to ~20 MB. Re-sending by file_id still works up to Telegram’s 2 GB upload limit. Files larger than 20 MB are still vaulted and shareable; hashes may be unavailable unless you run a local Bot API server.

Railway deploy (exact steps)

1. Create the bot token

1. Open Telegram → @BotFather
2. /newbot → choose name & username
3. Copy the token

2. Push this project to GitHub

cd FileHashVaultBot
git init
git add .
git commit -m "Initial FileHashVaultBot"
# create an empty GitHub repo, then:
git remote add origin https://github.com/<you>/FileHashVaultBot.git
git branch -M main
git push -u origin main

3. Create a Railway project

1. Go to https://railway.app and sign in
2. New Project → Deploy from GitHub repo
3. Select FileHashVaultBot
4. Railway will detect Python via Nixpacks

4. Configure the service

1. Open the service → Variables
2. Add:

BOT_TOKEN=123456:ABC-your-token
ADMIN_ID=your_numeric_telegram_id

3. Optional:

LOG_LEVEL=INFO
DATABASE_PATH=/data/vault.db

4. Settings → Deploy
   • Start command (if not using railway.json / Procfile): python bot.py
   • This must be a worker (long-running polling process), not a one-shot web build

5. Persist SQLite (recommended)

Railway free/ephemeral disks lose files on redeploy. For better durability:

1. Service → Settings → Volumes
2. Mount a volume at /data
3. Set DATABASE_PATH=/data/vault.db

Without a volume the bot still works; vault.db is recreated after redeploys and old share codes are lost.

6. Deploy & verify

1. Click Deploy
2. Open Logs — you should see: Bot started as @YourBot
3. In Telegram, send /start to your bot, then upload a small file
4. Confirm you receive hashes + a 6-char code
5. Send the code back → file should return

Railway notes

• Use polling (this project). No public HTTP port / webhook domain required.
• Procfile contains: worker: python bot.py
• railway.json sets startCommand to python bot.py
• Free tier sleeps / limits apply; if the dyno sleeps, the bot is offline until woken (Railway policy dependent)
• Never commit real .env or vault.db

Security model

• Download: anyone with the share code can retrieve the file while it is valid
• Delete: only the original uploader_id can delete that code
• Codes use a non-ambiguous alphabet and 6 chars (32^6 space)
• Do not share codes for sensitive files in public channels

Manual test checklist

• /start shows Persian welcome
• Upload document → hashes + code + buttons
• Upload photo / video / audio
• /get CODE returns file
• Plain text code returns file
• Deep link t.me/<bot>?start=CODE works for a new user chat
• 📋 کپی SHA256 sends monospace hash
• 🔗 لینک اشتراک sends deep link
• 🗑️ حذف works for uploader, denied for others
• /myfiles lists entries
• /clearme clears user rows
• Flood: 6th file within a minute is rejected

License

MIT — use and modify freely.