Next.js 15 da Telegram Mini ilovasi: HMAC-SHA256 orqali server tomonidan initData tekshiruvi
Nima uchun mijozga ishonolmaysiz
Mini ilovada user maydoniga ega window.Telegram.WebApp.initDataUnsafe obyekti mavjud. Ismni ko'rsatish uchun foydalanish qulay, lekin avtorizatsiya qilish uchun foydasiz: har kim sahifani oddiy brauzerda ochishi va o'zboshimchalik bilan id ni almashtirishi mumkin. Siz faqat Telegram.WebApp.initData qatoriga ishonishingiz mumkin va faqat server o'z imzosini bot tokeni bilan tekshirgandan keyingina.
Tekshirish algoritmi
initData - so'rovlar qatori formatidagi satr: query_id=...&user=%7B...%7D&auth_date=1700000000&hash=abc.... Telegram hujjatlaridan algoritm:
- 1.Satrni kalit-qiymat juftliklariga ajrating (qiymatlar URL-dekodlangan).
- 2.
hashmaydonini olib tashlang va qolgan juftlarni alifbo tartibida kalit bo'yicha tartiblang. - 3.Ularni yangi qator belgisi
\nbilan ajratilgankey=valueqatoriga birlashtiring. Bu ma'lumotlarni tekshirish qatori. - 4.Yashirin kalitni hisoblang:
secret_key = HMAC_SHA256(key = "WebAppData", message = bot_token). - 5.
HMAC_SHA256(key = secret_key, message = data_check_string)ni hisoblang va heksga aylantiring. - 6.
hashbilan solishtiring. Bundan tashqari,auth_datejuda eski emasligini tekshiring.
4-qadam - xatolarning asosiy joyi: "WebAppData" qatori kalit, bot belgisi esa xabardir. Ularni aralashtirib yuboring va imzo hech qachon mos kelmaydi.
Amalga oshirish
// 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"),
};
}Iltimos, diqqat qiling: faqat hash bundan mustasno. “Maʼlum” maydonlar roʻyxatini qoʻlda tuzmang - Telegram initData ga yangi maydonlarni qoʻshadi va mijozning keyingi yangilanishidan keyin qattiq kod chekni buzadi.
Mijozdan o'tkazish
"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}` },
});
}String qayta kodlanmasdan, avvalgidek uzatilishi kerak. Agar siz avval uni ob'ektga aylantirsangiz va keyin uni bir joyga qo'ysangiz, tartib va ekranlash o'zgaradi.
Marshrutni boshqaruvchi va sessiya
// 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 da cookies() asinxron, shuning uchun await. sameSite: "none" kerak, chunki Mini ilova o'rnatilgan WebViewda ochiladi va ba'zi mijozlarda bu uchinchi tomon konteksti sifatida qabul qilinadi. Cookie-fayllarga alternativa har bir soʻrovda initData ni tekshirish hisoblanadi: bu oddiyroq va sessiya saqlashni talab qilmaydi, lekin auth_date yangiligi bilan cheklangan.
Agar sizga Edge Runtime kerak bo'lsa
node:crypto Edge'da mavjud emas. Web Crypto-da bir xil mantiq:
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) -> hexUshbu versiyada olti burchakli satrlarni === orqali emas, balki doimiy vaqtda (barcha belgilar ustida XOR bilan tsikl) solishtiring.
Mos kelmaydigan xeshni tuzatish
- Haqiqiy mijozdan
initDatani oling va uni alohida skriptdagi funksiya bilan tekshiring - bu bilan siz algoritm xatosini transport xatosidan ajratasiz. - Token Mini Ilova ochiladigan botga tegishli ekanligiga ishonch hosil qiling. Sinov va jangovar botlarda turli tokenlar mavjud.
- Proksi yoki ramka uzun sarlavhani kesib tashlayotganligini tekshiring.
- Hisoblash vaqtida jurnallar
%7Bqiymatidauserko'rsatsa, bu siz qiymatlarni dekodlamaganingizni bildiradi.URLSearchParamsbuni o'zi bajaradi.
Qachonki yetarli bo'lmasa
initData tekshiruvi maʼlumotlar sizning botingiz uchun Telegram tomonidan chiqarilganligini tasdiqlaydi, lekin maxAgeSec davomida ushlangan qatordan qayta foydalanishdan himoya qilmaydi. Pul operatsiyalari uchun oynani qisqartiring va amallarni server seansiga bog'lang. Agar siz bot tokeniga kira olmasdan maʼlumotlarni tekshirishingiz kerak boʻlsa (masalan, hamkor tomonida), Telegram’da signature maydoni va Ed25519 ochiq kaliti bilan alohida mexanizm mavjud – bu xuddi shu hujjatlarda tasvirlangan.