Next.js 15 पर टेलीग्राम मिनी ऐप: HMAC-SHA256 के माध्यम से सर्वर-साइड initData सत्यापन
आप ग्राहक पर भरोसा क्यों नहीं कर सकते
मिनी ऐप में, window.Telegram.WebApp.initDataUnsafe ऑब्जेक्ट user फ़ील्ड के साथ उपलब्ध है। नाम प्रदर्शित करने के लिए इसका उपयोग करना सुविधाजनक है, लेकिन प्राधिकरण के लिए यह बेकार है: कोई भी नियमित ब्राउज़र में पृष्ठ खोल सकता है और एक मनमाना id प्रतिस्थापित कर सकता है। आप केवल स्ट्रिंग Telegram.WebApp.initData पर भरोसा कर सकते हैं, और केवल तभी जब सर्वर आपके बॉट के टोकन के साथ अपने हस्ताक्षर को सत्यापित करता है।
सत्यापन एल्गोरिथ्म
initData - क्वेरी स्ट्रिंग प्रारूप में एक स्ट्रिंग: query_id=...&user=%7B...%7D&auth_date=1700000000&hash=abc...। टेलीग्राम दस्तावेज़ से एल्गोरिदम:
- 1.स्ट्रिंग को कुंजी-मूल्य जोड़े में पार्स करें (मान यूआरएल-डिकोडेड हैं)।
- 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 को बाहर रखा गया है। "ज्ञात" फ़ील्ड की सूची मैन्युअल रूप से संकलित न करें - टेलीग्राम 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" की आवश्यकता है क्योंकि मिनी ऐप एक एम्बेडेड वेबव्यू में खुलता है, और कुछ क्लाइंट में इसे तीसरे पक्ष का संदर्भ माना जाता है। कुकीज़ का एक विकल्प प्रत्येक अनुरोध पर initData की जांच करना है: यह आसान है और इसके लिए सत्र भंडारण की आवश्यकता नहीं है, लेकिन यह auth_date की ताजगी से सीमित है।
यदि आपको एज रनटाइम की आवश्यकता है
node: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 चेक पुष्टि करता है कि डेटा आपके बॉट के लिए टेलीग्राम द्वारा जारी किया गया था, लेकिन maxAgeSec के दौरान इंटरसेप्टेड स्ट्रिंग के पुन: उपयोग से सुरक्षा नहीं देता है। पैसे के लेन-देन के लिए, विंडो को छोटा करें और क्रियाओं को सर्वर सत्र से जोड़ें। यदि आपको बॉट टोकन तक पहुंच के बिना डेटा की जांच करने की आवश्यकता है (उदाहरण के लिए, पार्टनर की ओर से), तो टेलीग्राम के पास signature फ़ील्ड और सार्वजनिक कुंजी Ed25519 के साथ एक अलग तंत्र है - यह उसी दस्तावेज़ में वर्णित है।