Telegram Mini App on Next.js 15: server-side initData verification via HMAC-SHA256
Почему нельзя верить клиенту
В Mini App доступен объект window.Telegram.WebApp.initDataUnsafe с полем user. Его удобно использовать для показа имени, но для авторизации он бесполезен: любой может открыть страницу в обычном браузере и подставить произвольный id. Доверять можно только строке Telegram.WebApp.initData, и только после того, как сервер проверит её подпись токеном вашего бота.
Алгоритм проверки
initData — строка в формате query string: query_id=...&user=%7B...%7D&auth_date=1700000000&hash=abc.... Алгоритм из документации Telegram:
- 1.Разобрать строку на пары ключ–значение (значения URL-декодируются).
- 2.Убрать поле
hash, остальные пары отсортировать по ключу в алфавитном порядке. - 3.Склеить их в строку
key=value, разделяя символом перевода строки\n. Это data-check-string. - 4.Вычислить секретный ключ:
secret_key = HMAC_SHA256(key = "WebAppData", message = bot_token). - 5.Вычислить
HMAC_SHA256(key = secret_key, message = data_check_string)и перевести в hex. - 6.Сравнить с
hash. Дополнительно проверить, чтоauth_dateне слишком старый.
Шаг 4 — главное место ошибок: строка "WebAppData" здесь ключ, а токен бота — сообщение. Перепутаете местами, и подпись не сойдётся никогда.
Реализация
// lib/telegram/verify-init-data.ts
import "server-only";
import { createHmac, timingSafeEqual } from "node:crypto";
export type TelegramUser = { id: number; first_name: string; last_name?: string; username?: string; language_code?: string };
export function verifyInitData(initData: string, botToken: string, maxAgeSec = 3600) {
const params = new URLSearchParams(initData);
const hash = params.get("hash");
if (!hash) return null;
params.delete("hash");
const dataCheckString = [...params.entries()]
.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
.map(([k, v]) => `${k}=${v}`)
.join("\n");
const secretKey = createHmac("sha256", "WebAppData").update(botToken).digest();
const computed = createHmac("sha256", secretKey).update(dataCheckString).digest("hex");
const a = Buffer.from(computed, "hex");
const b = Buffer.from(hash, "hex");
if (a.length !== b.length || !timingSafeEqual(a, b)) return null;
const authDate = Number(params.get("auth_date"));
if (!Number.isFinite(authDate) || Date.now() / 1000 - authDate > maxAgeSec) return null;
const userRaw = params.get("user");
return {
user: userRaw ? (JSON.parse(userRaw) as TelegramUser) : null,
authDate,
startParam: params.get("start_param"),
};
}Обратите внимание: исключается только hash. Не составляйте список «известных» полей вручную — Telegram добавляет новые поля в initData, и хардкод сломает проверку после очередного обновления клиента.
Передача с клиента
"use client";
export async function apiFetch(path: string, init: RequestInit = {}) {
const initData = window.Telegram?.WebApp?.initData ?? "";
return fetch(path, {
...init,
headers: { ...init.headers, Authorization: `tma ${initData}` },
});
}Строку нужно передавать как есть, без повторного кодирования. Если сначала превратить её в объект, а потом собрать обратно, порядок и экранирование изменятся.
Route Handler и сессия
// app/api/auth/telegram/route.ts
import { cookies } from "next/headers";
import { verifyInitData } from "@/lib/telegram/verify-init-data";
import { createSession } from "@/lib/session";
export const runtime = "nodejs";
export async function POST(req: Request) {
const auth = req.headers.get("authorization") ?? "";
if (!auth.startsWith("tma ")) return new Response("unauthorized", { status: 401 });
const result = verifyInitData(auth.slice(4), process.env.TELEGRAM_BOT_TOKEN!);
if (!result?.user) return new Response("invalid initData", { status: 401 });
const sessionId = await createSession({ telegramId: result.user.id });
(await cookies()).set("sid", sessionId, {
httpOnly: true, secure: true, sameSite: "none", path: "/", maxAge: 60 * 60 * 24 * 7,
});
return Response.json({ id: result.user.id, name: result.user.first_name });
}В Next.js 15 cookies() асинхронная, поэтому await. sameSite: "none" нужен, потому что Mini App открывается во встроенном WebView, и в некоторых клиентах это считается сторонним контекстом. Альтернатива cookie — проверять initData на каждом запросе: это проще и не требует хранилища сессий, но ограничено свежестью auth_date.
Если нужен Edge Runtime
node:crypto в Edge недоступен. Та же логика на Web Crypto:
async function hmac(key: BufferSource, data: string) {
const k = await crypto.subtle.importKey("raw", key, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
return new Uint8Array(await crypto.subtle.sign("HMAC", k, new TextEncoder().encode(data)));
}
// secret = await hmac(new TextEncoder().encode("WebAppData"), botToken)
// signature = await hmac(secret, dataCheckString) -> hexСравнение hex-строк в этом варианте делайте за постоянное время (цикл с XOR по всем символам), а не через ===.
Отладка несовпадающего hash
- Возьмите
initDataиз реального клиента и проверьте функцией в отдельном скрипте — так вы отделите ошибку алгоритма от ошибки транспорта. - Убедитесь, что токен принадлежит тому боту, через которого открыт Mini App. У тестового и боевого бота разные токены.
- Проверьте, не обрезает ли прокси или фреймворк длинный заголовок.
- Если в логах видно
%7Bв значенииuserпри расчёте, значит, вы не декодировали значения.URLSearchParamsделает это сам.
Когда этого недостаточно
Проверка initData подтверждает, что данные выдал Telegram для вашего бота, но не защищает от повторного использования перехваченной строки в течение maxAgeSec. Для операций с деньгами уменьшайте окно и привязывайте действия к серверной сессии. Если нужно проверять данные без доступа к токену бота (например, на стороне партнёра), у Telegram есть отдельный механизм с полем signature и публичным ключом Ed25519 — он описан в той же документации.