Telegram Mini App: получаем пользователя и безопасно проверяем initData

Telegram initData можно освоить на одном небольшом проекте, если сразу видеть вход, действие и результат. initData можно превратить в безопасную авторизацию без пароля, если проверить подпись на сервере и ограничить возраст данных. Ниже вы соберёте работающий пример и проверите обычный и граничный сценарии.

Объект initDataUnsafe удобен для интерфейса, но пользователь может подменить его в браузере, поэтому сервер не должен доверять этим полям. Поэтому отделим настройку, входные данные, основное действие и проверку. В этой статье вы соберёте серверную функцию проверки hash и auth_date, которая возвращает подтверждённого пользователя. Проверка: настоящая строка проходит, изменённое поле отклоняется, а старые данные получают отдельную ошибку.

Как устроен учебный проект Telegram initData

Telegram initData получает входные данные, проверяет их, выполняет одно внешнее действие и сохраняет наблюдаемый результат. Держите ввод, логику и отображение раздельно: тогда каждый этап можно проверить отдельно.

Контрольные точки: клиент, строка проверки, подпись и срок. Следующий шаг начинается после совпадения с ожидаемым результатом.

От входных данных до видимого результата. Сначала проверяется вход, затем действие и только потом интерфейс.

Собираем рабочий пример шаг за шагом

Материал сверялся с официальной документацией сервиса 21 октября 2026 года. Создайте Node.js проект. BOT_TOKEN храните только на сервере, клиент отправляет initData в теле HTTPS-запроса. Проверьте текущую папку через pwd или Get-Location. Вставьте пример целиком, выполните один раз, затем разбирайте по частям.

import crypto from 'node:crypto'

export function validateInitData(initData, botToken, maxAge = 3600) {
  const params = new URLSearchParams(initData)
  const receivedHash = params.get('hash')
  if (!receivedHash) return { ok: false, reason: 'hash missing' }
  params.delete('hash')
  const dataCheckString = [...params.entries()]
    .sort(([a], [b]) => a.localeCompare(b))
    .map(([key, value]) => key + '=' + value)
    .join('\n')
  const secret = crypto.createHmac('sha256', 'WebAppData')
    .update(botToken).digest()
  const expected = crypto.createHmac('sha256', secret)
    .update(dataCheckString).digest('hex')
  const valid = receivedHash.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(receivedHash), Buffer.from(expected))
  const authDate = Number(params.get('auth_date'))
  const fresh = Number.isFinite(authDate) && Date.now() / 1000 - authDate <= maxAge
  if (!valid) return { ok: false, reason: 'bad hash' }
  if (!fresh) return { ok: false, reason: 'expired' }
  return { ok: true, user: JSON.parse(params.get('user') || 'null') }
}

Главная функция принимает явные аргументы и возвращает данные, которые можно проверить отдельно от интерфейса. Найдите в примере вход, проверку и место формирования результата.

Что отличает устойчивый проект от случайного запуска. Явные границы делают ошибку локальной и понятной.

Что происходит внутри и почему это работает

Telegram и ваш сервер знают bot token. Из него выводится secret key, затем HMAC подписывает каноническую строку параметров. Сравнение hash доказывает целостность, но свежесть проверяется отдельно. Логику держите отдельно от вывода: функция получает аргумент и возвращает значение, а интерфейс показывает его. Секреты хранятся в переменных окружения и не попадают в исходники, журналы и скриншоты.

Успешная подпись не означает, что запрос нельзя повторить. Для чувствительных действий создайте серверную сессию, используйте CSRF-защиту по модели приложения и не принимайте платёжное действие только по одному initData. Не прячьте поток в одном обработчике: сохраните вход, проверьте его, вызовите операцию и только затем обновите интерфейс.

Проверяем проект и добавляем свою функцию

Сделайте endpoint /session, который принимает initData один раз и выдаёт короткую HttpOnly cookie. До правки запишите ожидаемое поведение одним предложением. После граничного теста повторите обычный сценарий.

После изменения повторите основной и ошибочный сценарии, чтобы новое поведение не сломало исходный результат. Полезная правка проходит от нового ввода до видимого результата.

Четыре проверки перед следующим шагом. Каждый следующий этап начинается после наблюдаемого результата.

Что запомнить и куда двигаться дальше

В интерфейсе можно показывать initDataUnsafe, но все права, баланс и действия проверяйте по подтверждённой серверной личности. Для закрепления откройте в REST API на Express, в первом проекте TypeScript и в WebSocket-чате.

Как изучить тему в Кодике

Сначала разберите формат данных и одну функцию, затем подключайте сеть, интерфейс или внешний сервис. Сначала восстановите главную функцию и проверьте её на трёх значениях.

Закрепите проект, переписав ключевую функцию по памяти и добавив собственный граничный случай. Базовый синтаксис закрепите через курс JavaScript.

Что получится в итоге

Финальный экран показывает результат, состояние запроса и понятное сообщение об ошибке без раскрытия секретов.