Начало темыИсходник

Telegram Mini App с нуля: поддельный initData, свой JWT и подписка, которую не выдать дважды

sonny_dsonny_dНовичок·11.11.2026· 0 ответов 0 реакций

Сначала про то, зачем это писалось. У меня был бот с подпиской, и на второй месяц кто-то открыл оплату в двух вкладках, заплатил один раз, а подписка включилась на два. Причина простая: обработчик successful_payment выдавал доступ сразу, как видел апдейт, и не смотрел, что этот же апдейт уже приходил. Telegram доставляет повторно — это его нормальное поведение, а не баг, и защищаться от него должен я. С тех пор я переписал всё это с нуля и в этот раз сначала проверил, что повтор ничего не ломает, а потом уже выложил.

Ниже — шаблон, который проходит путь от пустой папки до работающего платежа: проверка initData на сервере, JWT после неё, каталог, счёт, pre_checkout_query, выдача товара. Всё, что я утверждаю цифрами, прогнано на этой машине, транскрипт лежит в архиве целиком.

initData — это не «данные пользователя», это подписанный документ

Telegram отдаёт клиенту строку запроса: query_id, user (JSON, открытым текстом), auth_date, hash. Ключевое слово — открытым текстом. То есть user.id можно поменять в консоли на любой другой, и сервер, который читает это поле и верит ему, авторизует кого угодно под кем угодно. Проверка — единственное, что отделяет приложение от этого.

Схема из документации: из строки убирают hash, остальные пары сортируют по ключу, склеивают через перевод строки, считают HMAC. Ключ не сам токен бота, а производный:

secret_key = HMAC_SHA256(key="WebAppData", msg=bot_token)
hash       = hex(HMAC_SHA256(key=secret_key, msg=data_check_string))

Тут есть ловушка, на которой я просидел час. В новых клиентах в строке появилось поле signature — это третья схема подписи, на Ed25519, для проверки без токена бота. В data_check_string оно не входит. Если аккуратно убрать только hash, а signature оставить, HMAC не сойдётся никогда, и ты будешь смотреть на 401 при абсолютно правильном коде. Поэтому в verify() выкидываются оба поля, а не одно.

Вторая вещь, которую замечают позже, чем надо: порядок пар в исходной строке не важен. Сортировка всё равно, и первая версия моего теста на это и проверяет — строку переставляют, подпись остаётся валидной. Если у тебя после перестановки пар ломается проверка, значит ты склеиваешь строку в том порядке, в котором она пришла, и это ошибка.

Почему после проверки выдаётся свой токен

initData живёт сутки — Telegram ставит auth_date, и всё, что старше, надо отбивать. Я проверяю и на старость (сутки по умолчанию), и на «из будущего»: допуск 300 секунд на расхождение часов, дальше отказ. Без второй проверки подпись, сделанная с часами на год вперёд, будет валидной вечно — а подписать её может любой, кто знает токен бота, то есть в том числе тот, кто этот токен украл.

Дальше таскать initData в каждом запросе не надо, и это не оптимизация, а гигиена: суточный подписанный документ на клиенте — это суточный подписанный документ на клиенте. Сервер после проверки выдаёт JWT на час, sub — это user.id, и всё остальное ходит по Authorization: Bearer. JWT на стандартной библиотеке, сорок строк: подпись HS256, сравнение через hmac.compare_digest, проверка exp и alg. alg проверять обязательно — иначе кто-то пришлёт alg: none и токен станет просто текстом.

Платежи: три места, где теряют деньги

Цикл: клиент просит счёт → сервер пишет заказ в базу со статусом pending и зовёт createInvoiceLink → клиент открывает счёт через openInvoice → Telegram присылает pre_checkout_query → после оплаты приходит successful_payment.

Первое. На pre_checkout_query надо отвечать в течение десяти секунд, иначе счёт отменяется. И отвечать не безусловным ok: true, а проверкой: в апдейте лежат total_amount и currency. Если они не совпали с ценой каталога — отказ с текстом. Без этого сумму можно подменить на клиенте и купить годовой доступ за рубль.

Второе. Выдавать товар надо по payload, а не по сумме и не по user_id из апдейта. payload — своя строка, у меня sku:user_id:nonce, и она однозначно указывает на конкретный заказ. Сумма и валюта из successful_payment — только для сверки с заказом, не для поиска.

Третье, то самое, с чего я начал. successful_payment идемпотентен. В базе UNIQUE(payload), выдача — UPDATE ... WHERE status = 'pending', а повторный апдейт не отдаёт ни ошибку, ни товар второй раз. Ошибку отдавать нельзя: Telegram увидит 500 и будет ретраить, а ты получишь гонку на ровном месте.

Что показал прогон

25 тестов, все прошли. Дальше — не тесты, а живой uvicorn на свободном порту и настоящие HTTP-запросы через httpx. Список с результатами:

GET  /api/catalogue         200  товаров 2, первый: pro-month / 29900 RUB
POST /api/auth  (пусто)     401  initData: initData пустой
POST /api/auth  (подмена)   401  initData: hash не совпал
POST /api/auth  (просрочка) 401  initData: initData просрочен на 3600 с
POST /api/auth  (норма)     200  user=Идрис id=42
GET  /api/me  (битая подпись) 401  подпись не совпала
POST /api/checkout          200  https://t.me/$invoice_2acbd4a34fca
     payload pro-month:42:2acbd4a34fca
POST /api/telegram pre_checkout (цена 1)  200  ok=False  цена изменилась
POST /api/telegram successful_payment  200  status=paid charge=ch-live-1
POST /api/telegram повтор того же апдейта  200  status=paid (второй раз не выдаёт)

Подмена, которую я делаю в тесте, самая грубая: "id":42 меняется на "id":43 в уже собранной строке. Отказ — на хеше, до всякой логики. Ровно так это и должно работать: проверка подписи стоит первой, а не «после того, как мы посмотрели, что юзер не забанен».

Из мелкого, что видно в транскрипте и что стоит знать заранее: uvicorn в двух прогонах поднимался за 4.8 и за 9.6 секунды. Разница — холодный и прогретый кеш импорта fastapi, и это первая вещь, которая сбивает с толку, когда пишешь скрипт, который ждёт готовности сервера. Ждать надо /api/health, а не спать фиксированные секунды.

В базе после прогона один заказ: pro-month 29900 RUB paid ch-live-1. Один, а не два, хотя successful_payment приходил дважды. Это и есть та защита, из-за отсутствия которой я и переписывал всё.

Сеть в прогоне не участвует

Транспорт до api.telegram.org заменён классом, который записывает вызов и возвращает предсказуемый ответ. Поэтому прогон не ходит наружу вообще, а тесты не зависят от того, жив ли бот. В проде на это место ставится httpx и всё; createInvoiceLink в транскрипте — это не ответ Telegram, а то, что уйдёт в Telegram, и об этом надо помнить, читая строки выше.

Фронт: один файл, без сборки

Здесь я отступил от того, что планировал, и скажу прямо. Планировался React. npm на этой машине заблокирован групповой политикой, а класть в архив сборку, которую я не запускал, — это ровно тот случай, когда «в архиве есть» и «оно работает» расходятся. Поэтому фронт — один HTML с telegram-web-app.js: тема из themeParams, MainButton и BackButton, две раскладки через media query (телефон — одна колонка, десктопный клиент — две). Контракт API от фреймворка не зависит, React сюда добавляется без переделки бэка.

Вне Telegram страница ведёт себя честно, и это отдельно приятно: initData пустой, кнопка оплаты заблокирована, в статусе написано, почему. Никакой имитации работы.

Скриншот снят с запущенного сервера, а не нарисован. Это тот же index.html, который отдаёт GET / (5922 байта в транскрипте).

Деплой: что нужно и чего у меня нет

Mini App открывается внутри Telegram, то есть в iframe. Значит нужен настоящий HTTPS на домене: http:// клиент не примет, самоподписанный сертификат тоже. Порядок такой: BotFather, /newapp или Menu Button с URL вида https://app.example.com/, A-запись на сервер, certbot --nginx, setWebhook на /api/telegram.

В архиве лежат deploy/Dockerfile и deploy/nginx.conf. В nginx обязательны две вещи: не ставить X-Frame-Options: DENY (с ним iframe просто не откроется, и это неочевидно, потому что сама страница по прямой ссылке работает), и проксировать с X-Forwarded-Proto. В Dockerfile — --proxy-headers, без него FastAPI считает запрос http и любые абсолютные ссылки собирает неправильно. Оба файла не запускались: на этой машине нет докера. Они написаны по документации и лежат как отправная точка; если что-то в них не так, это выяснится у тебя, и я это честно помечаю, а не выдаю за проверенный деплой.

Чего здесь нет

Настоящий Telegram не поднимался: живой бот не создавался, вебхук не регистрировался, openInvoice не вызывался, деньги не двигались. Проверка secret_token у вебхука (заголовок X-Telegram-Bot-Api-Secret-Token) не сделана — это следующий шаг, и он важен, если домен светится. Возвраты и refunded не обрабатываются совсем. SQLite хватает на один процесс: с несколькими воркерами нужен Postgres или внешняя блокировка, иначе UNIQUE перестаёт спасать.

В архиве: app/ (initdata, token, pay, main), static/index.html, deploy/, tests/ на 25 штук, make_transcript.py, make_images.py и transcript.txt с полным выводом прогона — из него взяты все цифры выше. Ставится тремя командами из README: venv, pip install -r requirements.txt, uvicorn.

работает на моей машине — значит работает

Исходники
miniapp.zipЗарегистрируйтесь и поставьте реакцию на сообщение — исходник откроется.28 КБ

Комментарии

0
Пока нет комментариев. Войдите, чтобы ответить первым.