goyban
b7a0a86be2
Audit fixes: - Wallet names were used unvalidated as file paths, so a name like "../<other-id>/x" reached another user's wallet directory or overwrote bot_settings.json. Names are now validated and every path is resolved and confirmed to sit inside the caller's own directory, which also blocks a planted symlink from escaping. - Tor mode leaked: the mempool.space fee check opened a direct clear-net connection, tying the server's IP to its Bitcoin activity. It now goes through Tor's SOCKS proxy to mempool's onion service, DNS included. - The xpub message was left in the chat forever. It reveals the wallet's whole address and balance history, so it is now deleted like the password is. - Inline buttons stay live on old messages, so a user removed from the allow-list could keep using them. Callbacks re-check authorisation, and auth_check now works for callback queries instead of raising on a null message. - Wallet names echoed back in callback_data are confirmed against the user's real wallet list. - Settings are written via temp file + atomic rename; a crash mid-write used to truncate the file and lose every user's wallet selection. - Replies were sent against messages that had just been deleted; deletion is now best-effort and cannot abort the flow. Deployment: - Allow-list can come from ALLOWED_USERS instead of a bind-mounted file, so a deployment needs no files on disk. Both sources merge when both are present. - A missing bind-mounted allowed_users.txt made Docker create a directory in its place and silently lock everyone out; the entrypoint now detects that and stops with an explanation. - Standard mode honours ELECTRUM_SERVER, which previously only worked in Tor mode despite being documented. - Added VERSION, push.sh, docker-compose.deploy.yml and .env.deploy.example for a two-file deploy off the published image. Docs rewritten in English and Persian around the name Telegtrum, leading with the security model and what it does not protect against. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
227 lines
13 KiB
Markdown
227 lines
13 KiB
Markdown
# تله‌گتروم (Telegtrum)
|
||
|
||
**تلگرام + الکترום** — یک ربات تلگرام خودمیزبان برای مدیریت کیف‌پول‌های بیت‌کوین با Electrum.
|
||
|
||
تله‌گتروم برای **کیف‌پول‌های فقط-تماشا (xpub) با امضای آفلاین (air-gapped)** ساخته شده است. کلیدهای خصوصی شما هرگز روی سرور قرار نمی‌گیرند. ربات می‌تواند موجودی را ببیند، آدرس دریافت بسازد و تراکنش **امضانشده** بسازد؛ امضا فقط روی دستگاه آفلاین شما انجام می‌شود.
|
||
|
||
---
|
||
|
||
## مدل امنیتی — این بخش را حتماً بخوانید
|
||
|
||
| | |
|
||
|---|---|
|
||
| **سرور هیچ کلید خصوصی ندارد** | شما فقط **xpub** وارد می‌کنید. قابلیت تماشا دارد، نه خرج کردن. |
|
||
| **خرج کردن نیازمند دستگاه آفلاین است** | ربات تراکنش امضانشده می‌سازد؛ شما آن را جای دیگر امضا و برای انتشار برمی‌گردانید. |
|
||
| **دسترسی به‌صورت پیش‌فرض بسته است** | فقط شناسه‌های تلگرامی که شما تعیین کنید اجازه دارند. فهرست خالی یعنی هیچ‌کس اجازه ندارد. |
|
||
| **اطلاعات حساس از چت پاک می‌شوند** | رمز کیف‌پول و xpub بلافاصله پس از خوانده‌شدن حذف می‌شوند. |
|
||
| **کیف‌پول هر کاربر جداست** | هر کاربر پوشهٔ مخصوص خود را دارد و نام‌ها اعتبارسنجی می‌شوند تا کسی به فایل‌های دیگری دسترسی پیدا نکند. |
|
||
|
||
**در برابر چه چیزهایی محافظت نمی‌کند.** هر کسی که به حساب تلگرام شما دسترسی داشته باشد می‌تواند موجودی و آدرس‌ها را ببیند و تراکنش بسازد (اما نمی‌تواند امضا کند). هر کسی که دسترسی root روی سرور داشته باشد می‌تواند فایل‌های کیف‌پول را بخواند و در لحظهٔ اجرای دستور Electrum رمز کیف‌پول را در فهرست پردازه‌ها ببیند — پس سرور را قابل‌اعتماد نگه دارید و فهرست مجاز را کوتاه. xpub شما یک راز حریم خصوصی است: هر کس آن را داشته باشد تمام تاریخچهٔ تراکنش‌های شما را برای همیشه می‌بیند.
|
||
|
||
---
|
||
|
||
## راه‌اندازی سریع (پیشنهادی)
|
||
|
||
بدون کلون کردن مخزن و بدون build. فقط دو فایل و یک دستور.
|
||
|
||
```bash
|
||
mkdir telegtrum && cd telegtrum
|
||
|
||
curl -O https://git.goyban.com/goyban/telegtrum_bot/raw/branch/main/docker-compose.deploy.yml
|
||
curl -o .env https://git.goyban.com/goyban/telegtrum_bot/raw/branch/main/.env.deploy.example
|
||
|
||
nano .env # توکن ربات و شناسه کاربری تلگرام خود را وارد کنید
|
||
docker compose -f docker-compose.deploy.yml up -d
|
||
docker compose -f docker-compose.deploy.yml logs -f
|
||
```
|
||
|
||
فایل `.env` به دو مقدار نیاز دارد:
|
||
|
||
```dotenv
|
||
TELEGRAM_BOT_TOKEN=123456:ABC... # از @BotFather
|
||
ALLOWED_USERS=123456789 # از @userinfobot، برای چند نفر با کاما جدا کنید
|
||
```
|
||
|
||
اگر `ALLOWED_USERS` تنظیم نشده باشد، compose اجرا نمی‌شود — به‌جای اینکه رباتی بالا بیاید که هیچ‌کس نتواند از آن استفاده کند.
|
||
|
||
باید پیام `Electrum daemon started. Launching bot...` را ببینید. سپس در تلگرام به ربات پیام دهید و **Add Wallet** را بزنید.
|
||
|
||
### به‌روزرسانی
|
||
|
||
```bash
|
||
docker compose -f docker-compose.deploy.yml pull
|
||
docker compose -f docker-compose.deploy.yml up -d
|
||
```
|
||
|
||
اطلاعات کیف‌پول در ولوم `telegtrum-data` باقی می‌ماند و با به‌روزرسانی از بین نمی‌رود.
|
||
|
||
---
|
||
|
||
## پیش‌نیازها
|
||
|
||
- یک سرور لینوکسی با Docker و Docker Compose
|
||
- توکن ربات تلگرام — [@BotFather](https://t.me/BotFather)
|
||
- شناسه کاربری تلگرام شما — [@userinfobot](https://t.me/userinfobot)
|
||
|
||
---
|
||
|
||
## ساخت از روی سورس
|
||
|
||
فقط اگر می‌خواهید ربات را تغییر دهید.
|
||
|
||
```bash
|
||
git clone https://git.goyban.com/goyban/telegtrum_bot.git
|
||
cd telegtrum_bot
|
||
cp .env.example .env && nano .env
|
||
docker compose up -d --build
|
||
```
|
||
|
||
در این حالت فایل `bot.py` به‌صورت read-only مانت می‌شود، پس می‌توانید آن را ویرایش کنید و فقط `docker compose restart` بزنید.
|
||
|
||
### فهرست کاربران مجاز: فایل یا متغیر محیطی
|
||
|
||
هر دو کار می‌کنند؛ اگر هر دو را استفاده کنید، با هم ادغام می‌شوند.
|
||
|
||
**متغیر محیطی** (ساده‌ترین راه — نیازی به مانت فایل نیست):
|
||
```dotenv
|
||
ALLOWED_USERS=123456789,987654321
|
||
```
|
||
|
||
**فایل** — `allowed_users.txt`، هر کاربر در یک خط، به شکل `id, Name`:
|
||
```bash
|
||
cp allowed_users.txt.example allowed_users.txt
|
||
```
|
||
```
|
||
123456789, Alice
|
||
```
|
||
|
||
> اگر `allowed_users.txt` را مانت کنید ولی فایل وجود نداشته باشد، داکر بی‌سروصدا یک **پوشه** به‌جای آن می‌سازد و هیچ‌کس نمی‌تواند وارد شود. اکنون کانتینر این حالت را تشخیص می‌دهد و با پیام روشن متوقف می‌شود.
|
||
|
||
### انتشار ایمیج جدید
|
||
|
||
```bash
|
||
./push.sh # نسخه از فایل VERSION خوانده می‌شود
|
||
./push.sh 1.0.1 # یا نسخه را مستقیم بدهید
|
||
```
|
||
|
||
---
|
||
|
||
## حالت‌های اتصال
|
||
|
||
### استاندارد — سرورهای عمومی Electrum
|
||
|
||
حالت پیش‌فرض. برای اتصال فقط به یک سرور مشخص:
|
||
|
||
```dotenv
|
||
ELECTRUM_SERVER=192.168.1.100:50001:t
|
||
```
|
||
|
||
### محلی / Umbrel — نود شخصی شما
|
||
|
||
```bash
|
||
cp .env.example .env # مقادیر TELEGRAM_BOT_TOKEN و UMBREL_IP را تنظیم کنید
|
||
docker compose -f docker-compose.local.yml up -d --build
|
||
```
|
||
|
||
> آدرس `umbrel.local` داخل کانتینر **کار نمی‌کند** — mDNS فقط روی خود میزبان در دسترس است. از IP واقعی استفاده کنید، مثلاً `192.168.1.100`.
|
||
|
||
در اولین اجرا فایل `./electrum-data/config` با همان سرور نوشته می‌شود. اگر فایل از قبل باشد دست نمی‌خورد، پس تغییرات دستی شما باقی می‌مانند.
|
||
|
||
> اگر وصل نشد، بررسی کنید رشتهٔ سرور در `./electrum-data/config` هنوز به `:t` (یعنی TCP) ختم شود. گاهی Electrum آن را به `:s` (SSL) تغییر می‌دهد. کانتینر را متوقف کنید، برگردانید و دوباره اجرا کنید.
|
||
|
||
### Tor
|
||
|
||
```bash
|
||
cp .env.tor.example .env
|
||
docker compose -f docker-compose.tor.yml up -d --build
|
||
```
|
||
|
||
یا نود onion خودتان را بدهید:
|
||
```dotenv
|
||
ELECTRUM_SERVER=yournode123.onion:50001:t
|
||
```
|
||
…یا خالی بگذارید تا از سرور onion عمومی استفاده شود (`electrums3lojbuj.onion:50001:t`، قابل تغییر با `ELECTRUM_ONION_SERVER`).
|
||
|
||
نکته‌ها:
|
||
- Tor داخل همان کانتینر اجرا می‌شود؛ entrypoint قبل از اجرای Electrum منتظر آماده‌شدن پروکسی SOCKS می‌ماند.
|
||
- **استعلام کارمزد هم از Tor عبور می‌کند.** از سرویس onion سایت mempool.space استفاده می‌شود، بنابراین بررسی کارمزد نمی‌تواند IP سرور شما را به فعالیت بیت‌کوینی‌تان ربط دهد.
|
||
- اطلاعات کیف‌پول در ولوم جداگانه (`electrum-tor-data`) نگهداری می‌شود.
|
||
- `:t` یعنی TCP — رمزنگاری را خود Tor انجام می‌دهد و SSL لازم نیست.
|
||
|
||
---
|
||
|
||
## کار با ربات
|
||
|
||
یک کیبورد ثابت در پایین چت نمایش داده می‌شود.
|
||
|
||
| دکمه | کاری که انجام می‌دهد |
|
||
|---|---|
|
||
| **Add Wallet** | افزودن کیف‌پول فقط-تماشا: نام ← xpub ← رمز. پیام حاوی xpub پس از خواندن حذف می‌شود. |
|
||
| **List** | فهرست کیف‌پول‌های شما. |
|
||
| **Load** | فعال‌کردن یک کیف‌پول (رمز می‌خواهد). برای Balance / Receive / Send لازم است. |
|
||
| **Balance** | موجودی تأییدشده و تأییدنشده. دکمه‌های شیشه‌ای واحد را بین BTC / mBTC / ساتوشی عوض می‌کنند. |
|
||
| **Receive** | یک آدرس دریافت استفاده‌نشدهٔ تازه. |
|
||
| **Send** | ساخت تراکنش **امضانشده** — پایین‌تر توضیح داده شده. |
|
||
| **Close** | خارج‌کردن کیف‌پول فعال از دیمن. |
|
||
| **🌐 Language** | تغییر بین فارسی و انگلیسی. |
|
||
|
||
نام کیف‌پول می‌تواند شامل حروف، اعداد، فاصله، نقطه، خط تیره و زیرخط باشد (۱ تا ۶۴ کاراکتر) و باید با حرف یا عدد شروع شود. رمز باید حداقل ۸ کاراکتر و شامل حرف بزرگ، حرف کوچک و عدد باشد.
|
||
|
||
### ارسال
|
||
|
||
۱. **Send** ← انتخاب منبع کارمزد: **Electrum** یا **mempool.space** (زنده)
|
||
۲. نرخ کارمزد را بر حسب sat/vB وارد کنید
|
||
۳. رمز کیف‌پول را وارد کنید *(پیام بلافاصله حذف می‌شود)*
|
||
۴. آدرس مقصد را وارد کنید
|
||
۵. مبلغ را وارد کنید یا **Send Max** را بزنید
|
||
۶. تراکنش امضانشده را هم به‌صورت متن و هم فایل `.txt` دریافت می‌کنید
|
||
۷. آن را آفلاین امضا کنید — الکترومِ اندروید: *Send ← Paste from clipboard*؛ نسخهٔ دسکتاپ: *Send ← آیکون ابزار ← Read text from file*
|
||
۸. **Send ← Broadcast** و تراکنش امضاشده را بچسبانید
|
||
|
||
---
|
||
|
||
## پشتیبان‌گیری
|
||
|
||
همه چیز — کیف‌پول‌ها، تنظیمات و هدرهای بلاک‌چین — در یک ولوم است.
|
||
|
||
```bash
|
||
# حالت راه‌اندازی سریع
|
||
docker run --rm -v telegtrum-data:/data -v "$PWD":/backup debian:bookworm-slim \
|
||
tar czf /backup/telegtrum-backup.tar.gz -C /data .
|
||
```
|
||
|
||
| حالت | ولوم |
|
||
|---|---|
|
||
| راه‌اندازی سریع | `telegtrum-data` |
|
||
| ساخت از سورس | `electrum-data` |
|
||
| Tor | `electrum-tor-data` |
|
||
| محلی / Umbrel | `./electrum-data` (bind mount) |
|
||
|
||
پشتیبان جای عبارت بازیابی (seed) را نمی‌گیرد. اینها کیف‌پول فقط-تماشا هستند؛ چیزی که واقعاً دارایی شما را برمی‌گرداند، seed روی دستگاه آفلاین شماست.
|
||
|
||
---
|
||
|
||
## رفع اشکال
|
||
|
||
**ربات پاسخ نمی‌دهد** — با `docker compose logs -f` لاگ را ببینید. توکن را بررسی کنید و مطمئن شوید کانتینر مدام ری‌استارت نمی‌شود.
|
||
|
||
**«شما مجاز به استفاده از این ربات نیستید»** — شناسهٔ شما در `ALLOWED_USERS` یا `allowed_users.txt` نیست. اضافه و ری‌استارت کنید.
|
||
|
||
**همه رد می‌شوند** — اگر هر دو منبع خالی باشند، کانتینر هنگام اجرا پیام `no allowed users configured` را ثبت می‌کند.
|
||
|
||
**«کیف‌پولی بارگذاری نشده»** — اول **Load** را بزنید؛ Balance و Receive و Send همگی به کیف‌پول فعال نیاز دارند.
|
||
|
||
**نام کیف‌پول نامعتبر** — فقط حروف، اعداد، فاصله، نقطه، خط تیره و زیرخط.
|
||
|
||
**دیمن اجرا نمی‌شود** — entrypoint در هر اجرا فایل قفل قدیمی را پاک می‌کند. اگر باز هم بود، `docker compose restart` بزنید.
|
||
|
||
**Tor وصل نمی‌شود** — راه‌اندازی اولیهٔ Tor ممکن است حدود ۳۰ ثانیه طول بکشد.
|
||
|
||
---
|
||
|
||
## اطمینان از چیزی که اجرا می‌کنید
|
||
|
||
ایمیج، Electrum را از روی تاربالِ رسمی می‌سازد و **امضای GPG آن را با اثرانگشت‌های پین‌شدهٔ کلیدهای انتشار** (ThomasV و sombernight و Emzy) بررسی می‌کند. اگر امضا نباشد یا اثرانگشت نخواند، build شکست می‌خورد و کیف‌پول تأییدنشده منتشر نمی‌شود.
|
||
|
||
می‌توانید خودتان با `./push.sh` بازتولیدش کنید — یا فایل [`install.sh`](install.sh) را بخوانید، فقط ۶۰ خط است.
|