تطبيق Telegram Mini على Next.js 15: التحقق من initData من جانب الخادم عبر HMAC-SHA256
لماذا لا يمكنك الوثوق بالعميل
في التطبيق المصغر، يتوفر الكائن window.Telegram.WebApp.initDataUnsafe مع الحقل user. من السهل استخدامه لعرض الاسم، ولكنه غير مفيد للحصول على ترخيص: يمكن لأي شخص فتح الصفحة في متصفح عادي واستبدال id بشكل عشوائي. لا يمكنك الوثوق إلا بالسلسلة Telegram.WebApp.initData، وذلك فقط بعد أن يتحقق الخادم من توقيعه باستخدام الرمز المميز لروبوتك.
خوارزمية التحقق
initData - سلسلة بتنسيق سلسلة الاستعلام: query_id=...&user=%7B...%7D&auth_date=1700000000&hash=abc.... الخوارزمية من وثائق Telegram:
- 1.قم بتحليل السلسلة إلى أزواج قيمة المفتاح (يتم فك تشفير القيم بواسطة عنوان URL).
- 2.قم بإزالة الحقل
hashوفرز الأزواج المتبقية حسب المفتاح بالترتيب الأبجدي. - 3.قم بتسلسلها في سلسلة
key=value، مفصولة بحرف السطر الجديد\n. هذه سلسلة فحص البيانات. - 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 مضمن، وفي بعض العملاء يعتبر هذا سياقًا لجهة خارجية. بديل ملفات تعريف الارتباط هو التحقق من 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من عميل حقيقي وتحقق منه باستخدام وظيفة في برنامج نصي منفصل - وبهذه الطريقة ستفصل خطأ الخوارزمية عن خطأ النقل. - تأكد من أن الرمز المميز ينتمي إلى الروبوت الذي يتم من خلاله فتح التطبيق المصغر. الروبوتات الاختبارية والقتال لها رموز مختلفة.
- تحقق مما إذا كان الوكيل أو إطار العمل يقطع الرأس الطويل.
- إذا أظهرت السجلات
%7Bفي قيمةuserأثناء الحساب، فهذا يعني أنك لم تقم بفك تشفير القيم.URLSearchParamsيقوم بذلك بنفسه.
عندما لا يكون ذلك كافيا
يؤكد فحص initData أن البيانات قد تم إصدارها بواسطة Telegram لروبوتك، لكنه لا يحمي من إعادة استخدام السلسلة التي تم اعتراضها أثناء maxAgeSec. بالنسبة للمعاملات المالية، قم بتقليل النافذة واربط الإجراءات بجلسة الخادم. إذا كنت بحاجة إلى التحقق من البيانات دون الوصول إلى رمز الروبوت المميز (على سبيل المثال، من جانب الشريك)، فلدى Telegram آلية منفصلة مع الحقل signature والمفتاح العام Ed25519 - وهو موضح في نفس الوثائق.