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>
13 KiB
تله‌گتروم (Telegtrum)
تلگرام + الکترום — یک ربات تلگرام خودمیزبان برای مدیریت کیف‌پول‌های بیت‌کوین با Electrum.
تله‌گتروم برای کیف‌پول‌های فقط-تماشا (xpub) با امضای آفلاین (air-gapped) ساخته شده است. کلیدهای خصوصی شما هرگز روی سرور قرار نمی‌گیرند. ربات می‌تواند موجودی را ببیند، آدرس دریافت بسازد و تراکنش امضانشده بسازد؛ امضا فقط روی دستگاه آفلاین شما انجام می‌شود.
مدل امنیتی — این بخش را حتماً بخوانید
| سرور هیچ کلید خصوصی ندارد | شما فقط xpub وارد می‌کنید. قابلیت تماشا دارد، نه خرج کردن. |
| خرج کردن نیازمند دستگاه آفلاین است | ربات تراکنش امضانشده می‌سازد؛ شما آن را جای دیگر امضا و برای انتشار برمی‌گردانید. |
| دسترسی به‌صورت پیش‌فرض بسته است | فقط شناسه‌های تلگرامی که شما تعیین کنید اجازه دارند. فهرست خالی یعنی هیچ‌کس اجازه ندارد. |
| اطلاعات حساس از چت پاک می‌شوند | رمز کیف‌پول و xpub بلافاصله پس از خوانده‌شدن حذف می‌شوند. |
| کیف‌پول هر کاربر جداست | هر کاربر پوشهٔ مخصوص خود را دارد و نام‌ها اعتبارسنجی می‌شوند تا کسی به فایل‌های دیگری دسترسی پیدا نکند. |
در برابر چه چیزهایی محافظت نمی‌کند. هر کسی که به حساب تلگرام شما دسترسی داشته باشد می‌تواند موجودی و آدرس‌ها را ببیند و تراکنش بسازد (اما نمی‌تواند امضا کند). هر کسی که دسترسی root روی سرور داشته باشد می‌تواند فایل‌های کیف‌پول را بخواند و در لحظهٔ اجرای دستور Electrum رمز کیف‌پول را در فهرست پردازه‌ها ببیند — پس سرور را قابل‌اعتماد نگه دارید و فهرست مجاز را کوتاه. xpub شما یک راز حریم خصوصی است: هر کس آن را داشته باشد تمام تاریخچهٔ تراکنش‌های شما را برای همیشه می‌بیند.
راه‌اندازی سریع (پیشنهادی)
بدون کلون کردن مخزن و بدون build. فقط دو فایل و یک دستور.
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 به دو مقدار نیاز دارد:
TELEGRAM_BOT_TOKEN=123456:ABC... # از @BotFather
ALLOWED_USERS=123456789 # از @userinfobot، برای چند نفر با کاما جدا کنید
اگر ALLOWED_USERS تنظیم نشده باشد، compose اجرا نمی‌شود — به‌جای اینکه رباتی بالا بیاید که هیچ‌کس نتواند از آن استفاده کند.
باید پیام Electrum daemon started. Launching bot... را ببینید. سپس در تلگرام به ربات پیام دهید و Add Wallet را بزنید.
به‌روزرسانی
docker compose -f docker-compose.deploy.yml pull
docker compose -f docker-compose.deploy.yml up -d
اطلاعات کیف‌پول در ولوم telegtrum-data باقی می‌ماند و با به‌روزرسانی از بین نمی‌رود.
پیش‌نیازها
- یک سرور لینوکسی با Docker و Docker Compose
- توکن ربات تلگرام — @BotFather
- شناسه کاربری تلگرام شما — @userinfobot
ساخت از روی سورس
فقط اگر می‌خواهید ربات را تغییر دهید.
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 بزنید.
فهرست کاربران مجاز: فایل یا متغیر محیطی
هر دو کار می‌کنند؛ اگر هر دو را استفاده کنید، با هم ادغام می‌شوند.
متغیر محیطی (ساده‌ترین راه — نیازی به مانت فایل نیست):
ALLOWED_USERS=123456789,987654321
فایل — allowed_users.txt، هر کاربر در یک خط، به شکل id, Name:
cp allowed_users.txt.example allowed_users.txt
123456789, Alice
اگر
allowed_users.txtرا مانت کنید ولی فایل وجود نداشته باشد، داکر بی‌سروصدا یک پوشه به‌جای آن می‌سازد و هیچ‌کس نمی‌تواند وارد شود. اکنون کانتینر این حالت را تشخیص می‌دهد و با پیام روشن متوقف می‌شود.
انتشار ایمیج جدید
./push.sh # نسخه از فایل VERSION خوانده می‌شود
./push.sh 1.0.1 # یا نسخه را مستقیم بدهید
حالت‌های اتصال
استاندارد — سرورهای عمومی Electrum
حالت پیش‌فرض. برای اتصال فقط به یک سرور مشخص:
ELECTRUM_SERVER=192.168.1.100:50001:t
محلی / Umbrel — نود شخصی شما
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
cp .env.tor.example .env
docker compose -f docker-compose.tor.yml up -d --build
یا نود onion خودتان را بدهید:
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 و تراکنش امضاشده را بچسبانید
پشتیبان‌گیری
همه چیز — کیف‌پول‌ها، تنظیمات و هدرهای بلاک‌چین — در یک ولوم است.
# حالت راه‌اندازی سریع
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 را بخوانید، فقط ۶۰ خط است.