Ứng dụng Telegram Mini trên Next.js 15: xác minh initData phía máy chủ thông qua HMAC-SHA256
Tại sao bạn không thể tin tưởng khách hàng
Trong Ứng dụng nhỏ, đối tượng window.Telegram.WebApp.initDataUnsafe có trường user khả dụng. Nó rất thuận tiện khi sử dụng để hiển thị tên, nhưng nó vô dụng cho việc ủy quyền: bất kỳ ai cũng có thể mở trang trong trình duyệt thông thường và thay thế bằng id tùy ý. Bạn chỉ có thể tin cậy chuỗi Telegram.WebApp.initData và chỉ sau khi máy chủ xác minh chữ ký của nó bằng mã thông báo bot của bạn.
Thuật toán xác minh
initData - một chuỗi ở định dạng chuỗi truy vấn: query_id=...&user=%7B...%7D&auth_date=1700000000&hash=abc.... Thuật toán từ tài liệu Telegram:
- 1.Phân tích chuỗi thành các cặp khóa-giá trị (các giá trị được giải mã URL).
- 2.Xóa trường
hashvà sắp xếp các cặp còn lại theo khóa theo thứ tự bảng chữ cái. - 3.Nối chúng thành một chuỗi
key=value, cách nhau bằng ký tự dòng mới\n. Đây là chuỗi kiểm tra dữ liệu. - 4.Tính khóa bí mật:
secret_key = HMAC_SHA256(key = "WebAppData", message = bot_token). - 5.Tính
HMAC_SHA256(key = secret_key, message = data_check_string)và chuyển đổi sang dạng hex. - 6.So sánh với
hash. Ngoài ra, hãy kiểm tra xemauth_datecó quá cũ không.
Bước 4 là nơi xảy ra lỗi chính: dòng "WebAppData" là khóa và mã thông báo bot là thông báo. Hãy trộn lẫn chúng và chữ ký sẽ không bao giờ khớp.
Triển khai
// 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"),
};
}Xin lưu ý: chỉ hash bị loại trừ. Không biên soạn danh sách các trường “đã biết” theo cách thủ công - Telegram thêm các trường mới vào initData và mã cứng sẽ phá vỡ kiểm tra sau lần cập nhật ứng dụng khách tiếp theo.
Chuyển từ khách hàng
"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}` },
});
}Chuỗi phải được truyền nguyên trạng mà không cần mã hóa lại. Nếu trước tiên bạn biến nó thành một đồ vật rồi ghép lại với nhau, thứ tự và lớp chắn sẽ thay đổi.
Trình xử lý tuyến đường và phiên
// 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 });
}Trong Next.js 15, cookies() không đồng bộ, vì vậy await. sameSite: "none" là cần thiết vì Ứng dụng mini mở trong WebView được nhúng và trong một số ứng dụng khách, đây được coi là bối cảnh của bên thứ ba. Một cách thay thế cho cookie là kiểm tra initData theo mọi yêu cầu: việc này đơn giản hơn và không yêu cầu lưu trữ phiên nhưng bị hạn chế bởi tính mới của auth_date.
Nếu bạn cần Edge Runtime
node:crypto không khả dụng trong Edge. Logic tương tự trên 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) -> hexTrong phiên bản này, so sánh các chuỗi hex theo thời gian không đổi (vòng lặp với XOR trên tất cả các ký tự) chứ không phải thông qua ===.
Gỡ lỗi hàm băm không khớp
- Lấy
initDatatừ một máy khách thực và kiểm tra nó bằng một hàm trong một tập lệnh riêng - bằng cách này, bạn sẽ tách lỗi thuật toán khỏi lỗi truyền tải. - Đảm bảo rằng mã thông báo thuộc về bot mà qua đó Ứng dụng mini được mở. Các bot thử nghiệm và chiến đấu có các mã thông báo khác nhau.
- Kiểm tra xem proxy hoặc framework có cắt tiêu đề dài hay không.
- Nếu nhật ký hiển thị
%7Bở giá trịusertrong khi tính toán, điều đó có nghĩa là bạn đã không giải mã được các giá trị.URLSearchParamstự thực hiện việc này.
Khi không đủ
Kiểm tra initData xác nhận rằng dữ liệu do Telegram cấp cho bot của bạn nhưng không bảo vệ khỏi việc sử dụng lại chuỗi bị chặn trong maxAgeSec. Đối với các giao dịch tiền, hãy giảm cửa sổ và ràng buộc các hành động với phiên máy chủ. Nếu bạn cần kiểm tra dữ liệu mà không cần truy cập vào mã thông báo bot (ví dụ: từ phía đối tác), Telegram có cơ chế riêng với trường signature và khóa chung Ed25519 - nó được mô tả trong cùng một tài liệu.