Next.js 15 上的 Telegram Mini App:通过 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.将它们连接成字符串
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 中打开,并且在某些客户端中这被视为第三方上下文。 Cookie 的替代方法是在每个请求上检查 initData:这更简单,并且不需要会话存储,但受到 auth_date 新鲜度的限制。
如果您需要 Edge 运行时
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并使用单独脚本中的函数进行检查 - 这样您就可以将算法错误与传输错误分开。 - 确保该token属于打开小程序的机器人。测试机器人和战斗机器人有不同的令牌。
- 检查代理或框架是否正在切断长标头。
- 如果在计算过程中日志显示
user值中的%7B,则表示您没有对这些值进行解码。URLSearchParams本身会执行此操作。
当还不够的时候
initData 检查确认数据是由 Telegram 为您的机器人发出的,但不能防止在 maxAgeSec 期间重复使用截获的字符串。对于金钱交易,减少窗口并将操作与服务器会话联系起来。如果您需要在不访问机器人令牌的情况下检查数据(例如,在合作伙伴方面),Telegram 有一个单独的机制,其中包含 signature 字段和公钥 Ed25519 - 它在同一文档中进行了描述。