NodeGram چگونه دسترسی امن سرور به Telegram Bot API را حل می‌کند؟

خیلی از اپلیکیشن‌ها می‌خواهند با ربات تلگرام پیام بفرستند: هشدار استقرار، فرم تماس، اعلان وضعیت. مسیر رسمی مشخص است. Telegram Bot API روی https://api.telegram.org متدهایی مثل ارسال پیام را با توکن ربات می‌پذیرد. مسئله وقتی عملیاتی می‌شود که سرور اپلیکیشن به آن مبدأ نمی‌رسد. در آن حالت تیم‌ها وسوسه می‌شوند یک پروکسی عمومی، VPN، یا کلاینت کاربری تلگرام وسط بگذارند. این‌ها مسئلهٔ Bot API را حل نمی‌کنند؛ سطح حمله را عوض می‌کنند.

NodeGram در مخزن عمومی GitHub برای همان شکاف شبکه طراحی شده: یک درگاه کوچک و احرازهویت‌شده که اپلیکیشن به آن می‌رسد، درگاه درخواست را به Bot API رسمی می‌فرستد، و پاسخ تلگرام را برمی‌گرداند. پروژه متن‌باز NODE Group است. این مقاله فقط از README و اسناد عمومی همان مخزن و از مستندات عمومی تلگرام و DigitalOcean استفاده می‌کند. آدرس استقرار خصوصی، کلید واقعی و شناسهٔ گفت‌وگو اینجا نیست و نباید در بلاگ باشد.

مسئله شبکه است، نه کمبود متد ربات

Bot API یک رابط HTTP با JSON است. کلاینت متد را صدا می‌زند و نتیجه را می‌گیرد. اگر خروجی شبکهٔ سرور شما به مبدأ رسمی تلگرام بسته باشد، هر SDK همان خطا را می‌دهد. جابه‌جایی زبان کمکی نمی‌کند.

راه‌حل‌های غلط رایج را نام ببریم تا با NodeGram قاطی نشوند. تونل MTProto برای اپ کاربری تلگرام است، نه برای متد ارسال پیام سرور شما. VPN روی سرور اپ کل خروج را عوض می‌کند و مسئولیت جدا دارد. کلاینت کاربری خلاف مدل ربات است و توکن ربات نیست. پروکسی HTTP باز که URL مقصد را از کلاینت می‌گیرد، یعنی هر کسی بتواند درگاه شما را به هر میزبانی بفرستد؛ این SSRF است.

NodeGram خودش را در README به‌عنوان درگاه لایهٔ کاربرد برای Bot API رسمی تعریف می‌کند، روی DigitalOcean Functions. serverless است: یک Function که درخواست POST را می‌گیرد و به بالادست ثابت می‌زند. برای ترافیک نامنظم هشدار و فرم، این مدل از نگه داشتن یک ماشین مجازی پروکسی ساده‌تر است؛ به شرط آنکه محدوده را همان‌طور که طراحی شده نگه دارید.

چه چیزی هست و چه چیزی عمداً نیست

جملهٔ محصول را دقیق بخوانید: درگاه امن Telegram Bot API برای شبکه‌هایی که مستقیم به تلگرام نمی‌رسند. «امن» اینجا یعنی احراز هویت کلاینت درگاه، توکن ربات در بدنه نه در URL درگاه، بالادست سخت‌کدشده، و لاگ بدون راز. معجزهٔ ضدسانسور برای اپ موبایل تلگرام نیست.

README صریح است که NodeGram چیست و چیست نه:

• هست: رلهٔ متدهای رسمی Bot API با پارامتر JSON
• نیست: پروکسی MTProto
• نیست: VPN
• نیست: کلاینت اکانت کاربری تلگرام
• نیست: پروکسی عمومی HTTP که مقصد دلخواه بپذیرد

وابستگی سازمانی هم ندارد: نرم‌افزار مستقل است و وابسته یا تأییدشده توسط تلگرام یا DigitalOcean معرفی نشده است. این را در ارتباطات محصول تکرار کنید تا انتظار غلط نسازید.

مخزن با TypeScript نوشته شده و برای Functions بسته می‌شود. جزئیات استقرار در README است؛ اینجا همان قرارداد امنیتی را باز می‌کنیم که روی هر زبانی که HTTPS POST بزند قابل استفاده است.

مدل امنیتی: دو راز جدا، یک بالادست ثابت

دو راز با نقش متفاوت وجود دارد و قاطی‌کردنشان طراحی را خراب می‌کند.

کلید کلاینت درگاه با پیشوند ng_live_ در هدر Authorization به‌صورت Bearer می‌آید. این کلید ثابت می‌کند کدام اپلیکیشن حق دارد Function را صدا بزند. در پیکربندی درگاه فقط هش SHA-256 این کلیدها ذخیره می‌شود، نه خود کلید. برای هر محیط یا پروژه کلید جدا بسازید تا ابطال یکی بقیه را نکشد. چرخش یعنی هش جدید را اضافه کنید، کلاینت را عوض کنید، هش قدیم را حذف کنید.

توکن ربات تلگرام فیلد token در JSON بدنه است، در هر درخواست. توکن در مسیر یا رشتهٔ پرس‌وجوی درخواست به NodeGram نمی‌آید تا در لاگ پروکسی و access log لبه ننشیند. هر فراخواننده ربات خودش را می‌فرستد؛ درگاه چند پروژه را با کلیدهای جدا سرو می‌کند بدون اینکه توکن ربات را در پیکربندی خودش نگه دارد.

بالادست فقط https://api.telegram.org است. میزبان، پروتکل، پورت یا URL دلخواه از کلاینت پذیرفته نمی‌شود. همین سخت‌کد است که درگاه را از پروکسی باز جدا می‌کند و SSRF را در طراحی می‌بندد. واکشی بالادست نباید تغییر مسیر را دنبال کند تا توکن به میزبان دیگر نشت نکند.

بدون کلید معتبر، پاسخ عدم مجوز است. Function نباید رلهٔ ناشناس باشد. README صریح می‌گوید آن را به‌صورت رلهٔ عمومی ناشناس مستقر نکنید.

قرارداد درخواست: یک POST، سه میدان

کلاینت به یک URL Function با POST و JSON می‌زند. بدنه سه میدان دارد: توکن ربات، نام متد، و اختیاری پارامترها به‌صورت شیء. نام متد باید شبیه نام متد Bot API باشد؛ درگاه نام را محدود می‌کند تا رشتهٔ دلخواه مسیر نشود.

موفقیت یعنی وضعیت و بدنهٔ JSON تلگرام تا جای ممکن حفظ شود، نه اینکه NodeGram یک API موازی اختراع کند. خطاهای خود درگاه شکل پایدار دارند: فیلد عدم موفقیت و یک کد مثل درخواست نامعتبر، عدم مجوز، متد غیر POST، بدنهٔ بزرگ، محدودیت نرخ، یا خطای بالادست و زمان‌تمام.

سلامت جداست: درخواست GET با نشانهٔ سلامت، بدون چک تلگرام و بدون افشای پیکربندی. از این مسیر برای فهرست کلاینت‌ها یا اثر انگشت راز استفاده نکنید.

مثال‌های README با مقدار ساختگی‌اند. در کد خودتان از متغیر محیط بخوانید. توکن نمونه، کلید نمونه و شناسهٔ گفت‌وگوی نمونه را از بلاگ کپی نکنید و مقدار واقعی را در issue و چت عمومی نگذارید.

برای سروری که به تلگرام نمی‌رسد، این قرارداد یعنی سرور شما فقط باید به Function روی HTTPS برسد؛ مسیر رسمی bot و متد را خود درگاه به تلگرام می‌سازد و در لاگ نمی‌نویسد.

پشتیبانی‌شده و عمداً پشتیبانی‌نشده

نسخهٔ عمومی توصیف‌شده در README این‌ها را پشتیبانی می‌کند:

• متدهای رسمی با نام معتبر
• توکن ربات در هر درخواست
• پارامتر JSON
• شناسهٔ فایل موجود در تلگرام
• URL رسانه‌ای HTTPS عمومی که خود تلگرام بپذیرد
• polling کوتاه با محدودیت زمان نسبت به مهلت درگاه
• چند کلید کلاینت قابل ابطال
• POST روی همان endpoint درگاه، به‌جز مسیر سلامت

عمداً پشتیبانی نمی‌شود:

• MTProto، اکانت کاربری، پروکسی SOCKS یا HTTP، URL بالادست دلخواه
• آپلود باینری چندبخشی
• پروکسی دانلود فایل از تلگرام
• دریافت یا فوروارد وب‌هوک
• محدودیت نرخ توزیع‌شدهٔ تضمینی بدون ذخیرهٔ مشترک خارجی

این فهرست نقص تصادفی نیست؛ محدودیت Functions و مدل تهدید است. اگر آپلود بزرگ یا پخش وب‌هوک لازم دارید، README مسیر جدا روی بستر اپلیکیشن را پیشنهاد می‌کند، نه ضعیف‌کردن Function.

اسناد Bot API رسمی تلگرام برای فایل، هم ارسال چندبخشی و هم روش‌های مبتنی بر شناسهٔ فایل و URL را توضیح می‌دهد. NodeGram مسیر JSON را نگه می‌دارد؛ فایل را اول جایی عمومی یا با شناسهٔ فایل حل کنید، بعد متد را رله کنید.

محدودیت Functions همان محدودیت طراحی است

مستندات سقف‌های DigitalOcean Functions اندازهٔ پارامتر ورودی و اندازهٔ نتیجه را هر کدام یک مگابایت می‌گذارد. README همان سقف را به‌عنوان دلیل نپذیرفتن بدنهٔ بزرگ و رلهٔ باینری تکرار می‌کند. کدگذاری متنی بدنه را کوچک‌تر هم می‌کند. طراحی درست: رسانه از طریق شناسهٔ فایل یا URL عمومی، نه پیوست چندمگابایتی داخل JSON درگاه.

سقف‌های دیگر Functions — مهلت اجرا، حافظه، اندازهٔ بیلد — در همان صفحه آمده‌اند. README برای این درگاه حافظهٔ محافظه‌کارانه و مهلت کوتاه‌تر از سقف مطلق را هدف می‌گیرد تا Function آویزان نماند. زمان‌تمام بالادست باید قبل از کشتن زمان Function بسته شود.

محدودیت نرخ داخل یک نمونهٔ گرم، بهترین‌تلاش و درون‌حافظه است؛ بین نمونه‌ها به اشتراک گذاشته نمی‌شود. اگر سهمیهٔ سخت چندکلاینتی می‌خواهید، ذخیرهٔ مشترک یا درگاه جلویی جدا لازم است. این را در README به‌عنوان غیبت عمدی بخوانید، نه باگ.

یک درگاه serverless تلگرام با این سقف‌ها برای هشدار و متدهای JSON مناسب است، برای شبکهٔ تحویل فایل تلگرام مناسب نیست.

لاگ بدون بدن، بدون توکن، بدون گفت‌وگو

مشاهده‌پذیری درگاه نباید خودش نشت باشد. README یک خط لاگ JSON در هر درخواست را مجاز می‌داند با میدان‌هایی مثل زمان، شناسهٔ درخواست، شناسهٔ کلاینت غیرراز، در صورت پرچم صریح فقط شناسهٔ عددی ربات نه راز توکن، نام متد، کد نتیجهٔ درگاه، وضعیت بالادست، مدت، و نشانهٔ شروع سرد.

هرگز: بدنهٔ درخواست یا پاسخ، توکن ربات، کلید Bearer، شناسهٔ گفت‌وگو، متن پیام، URL بالادست حاوی توکن، یا پیکربندی راز.

این قرارداد را در اپ خودتان هم ادامه دهید. اگر سرور شما قبل از زدن به NodeGram متن پیام را در خروجی استاندارد می‌نویسد، درگاه هرقدر ساکت باشد شما نشت داده‌اید. لایهٔ تست و لاگ محصول را با ساخت مشاهده‌پذیری بدون دادهٔ خصوصی تراز کنید.

سلامت و خطاهای نگاشت‌شده نباید اثر انگشت کلید یا قطعهٔ توکن برگردانند.

استقرار و استفادهٔ مسئولانه

استقرار عمومی روی Functions در ناحیه‌ای است که هم به تلگرام برسد هم از سرورهای شما قابل فراخوانی باشد. فهرست کلاینت‌ها به‌صورت سند JSON کدشده در راز محیط می‌ماند. کدگذاری متنی رمزنگاری نیست؛ باید در راز رمزشدهٔ محیط بماند نه در Git.

بعد از استقرار، ترتیب دود: سلامت، سپس متد شناسایی ربات با توکن در بدنه، سپس ارسال پیام به یک گفت‌وگوی آزمایشی خصوصی. قبل از صحت پیکربندی، گفت‌وگوی تولید را هدف نگیرید.

کلاینت در هر زبانی که POST JSON بزند نوشته می‌شود. مقدار محیط را در مقاله نمی‌آوریم.

عامل هوش مصنوعی را روی این مخزن بدون پالایش راز راه نیندازید. قوانین زمینه و ممنوعیت چسباندن پروندهٔ محیط را در گردش‌کار توسعه با Cursor رعایت کنید. مسئولیت انطباق با شرایط تلگرام، سیاست DigitalOcean و قانون، با اپراتور است نه با درگاه. رلهٔ ناشناس عمومی خلاف مدل تهدید است.

مالکیت انسانی انتشار اینجا هم برقرار است: شتاب AI در تیم محصول مجوز دور زدن هش کلید و بالادست ثابت را نمی‌دهد.

کد، قرارداد API و اسناد معماری در مخزن GitHub NodeGram است. اگر از این مقاله یک کار می‌ماند، همان README را منبع حقیقت بگذارید نه نقل‌قول بلاگ.

پرسش‌های متداول

آیا NodeGram فیلترشکن تلگرام روی گوشی است؟

خیر. اپ کاربری تلگرام را باز نمی‌کند و ترافیک MTProto را از خودش عبور نمی‌دهد. فقط سرور شما می‌تواند متد Bot API را از طریق یک Function احرازهویت‌شده صدا بزند.

چرا توکن ربات در URL درگاه نیست؟

چون URL در لاگ لبه، مرورگر و سیستم‌های میانی می‌ماند. پاکت JSON روی HTTPS توکن را در بدنه می‌گذارد و README تأکید می‌کند توکن لاگ نشود. مسیر رسمی تلگرام توکن را در path بالادست دارد؛ آن path را درگاه می‌سازد و در لاگ نمی‌نویسد.

می‌توان وب‌هوک تلگرام را از همین Function گرفت؟

در طراحی فعلی خیر. دریافت و فوروارد وب‌هوک عمداً خارج از محدوده است. برای به‌روزرسانی‌ها، polling کوتاه با سقف زمان، یا سرویس جدا برای وب‌هوک، در README آمده است.

سقف یک مگابایت یعنی چه برای رسانه؟

یعنی بدنهٔ درخواست به Function و پاسخ برگشتی نمی‌توانند از این سقف مستند Functions بزرگ‌تر باشند. فایل بزرگ را داخل JSON نگذارید. شناسهٔ فایل یا URL عمومی HTTPS مسیری است که با این سقف می‌خواند.

NodeGram مسئلهٔ «سرور به Bot API نمی‌رسد» را با یک درگاه احرازهویت‌شده، توکن در بدنه، و بالادست ثابت حل می‌کند — نه با پروکسی باز و نه با VPN. اگر محدوده را همین نگه دارید، ابزار کوچکی برای هشدار و ربات سروری دارید. اگر محدوده را باز کنید، خودتان SSRF ساخته‌اید. قدم بعدی خواندن README مخزن و استقرار با کلید هش‌شده است، نه کپی توکن در تیکت.