Next.js 15 жүйесіндегі Telegram Mini қолданбасы: HMAC-SHA256 арқылы серверлік initData тексеруі
Неліктен клиентке сенуге болмайды
Шағын қолданбада user өрісі бар window.Telegram.WebApp.initDataUnsafe нысаны қолжетімді. Бұл атауды көрсету үшін пайдалану ыңғайлы, бірақ авторизациялау үшін пайдасыз: кез келген адам бетті қарапайым браузерде ашып, еркін id ауыстыра алады. Сіз тек Telegram.WebApp.initData жолына сене аласыз және сервер оның қолтаңбасын бот белгісімен тексергеннен кейін ғана.
Тексеру алгоритмі
initData - сұрау жолы пішіміндегі жол: query_id=...&user=%7B...%7D&auth_date=1700000000&hash=abc.... Telegram құжаттамасынан алгоритм:
- 1.Жолды кілт-мән жұптарына талдаңыз (мәндер URL-декодталған).
- 2.
hashөрісін алып тастаңыз және қалған жұптарды алфавиттік ретпен перне бойынша сұрыптаңыз. - 3.Оларды жаңа жол таңбасы
\nарқылы бөлінгенkey=valueжолына біріктіріңіз. Бұл деректерді тексеру жолы. - 4.Құпия кілтті есептеңіз:
secret_key = HMAC_SHA256(key = "WebAppData", message = bot_token). - 5.
HMAC_SHA256(key = secret_key, message = data_check_string)есептеп, он алтылыққа түрлендіріңіз. - 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}` },
});
}Жолды қайта кодтаусыз, сол күйінде жіберу керек. Егер сіз оны алдымен нысанға айналдырсаңыз, содан кейін қайта біріктірсеңіз, реті мен экрандауы өзгереді.
Маршрутты өңдеуші және сеанс
// 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" қажет, себебі Шағын қолданба ендірілген 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Бұл нұсқада === арқылы емес, тұрақты уақытта (барлық таңбалар бойынша XOR бар цикл) он алтылық жолдарын салыстырыңыз.
Сәйкес келмейтін хэшті жөндеу
- Нақты клиенттен
initDataалыңыз және оны бөлек сценарийдегі функциямен тексеріңіз - осылайша сіз алгоритм қатесін тасымалдау қателігінен ажыратасыз. - Токен шағын қолданба ашылатын ботқа тиесілі екеніне көз жеткізіңіз. Сынақ және жауынгерлік боттарда әртүрлі белгілер бар.
- Прокси немесе жақтау ұзын тақырыпты кесіп жатқанын тексеріңіз.
- Егер журналдар есептеу кезінде
userмәнінде%7Bкөрсетсе, бұл мәндерді декодтамағаныңызды білдіреді.URLSearchParamsмұны өзі жасайды.
Бұл жеткіліксіз болған кезде
initData тексеруі деректердің Telegram арқылы сіздің ботыңыз үшін шығарылғанын растайды, бірақ maxAgeSec кезінде ұсталған жолды қайта пайдаланудан қорғамайды. Ақша транзакциялары үшін терезені азайтып, әрекеттерді сервер сеансына байланыстырыңыз. Егер сізге бот токеніне қол жеткізбестен деректерді тексеру қажет болса (мысалы, серіктес жағында), Telegram-да signature өрісі және Ed25519 ашық кілті бар бөлек механизм бар - ол сол құжаттамада сипатталған.