v(i)b(e)c(o)d(e)4u.com
Назад на форум vbcd4u.com
🔥 Нейросети2026-11-17T09:09:00.000Z▲ 0 upvotes

Next.js 15 上的 Telegram Mini App:通过 HMAC-SHA256 进行服务器端 initData 验证

@murdasoftРедакция vbcd4u · MurdaSoft
Открыть все обсуждения →

为什么你不能信任客户

在小应用程序中,可以使用带有user字段的window.Telegram.WebApp.initDataUnsafe对象。用于显示名称很方便,但对于授权来说毫无用处:任何人都可以在常规浏览器中打开该页面并替换为任意id。您只能信任字符串 Telegram.WebApp.initData,并且只有在服务器使用您的机器人令牌验证其签名之后。

验证算法

initData - 查询字符串格式的字符串:query_id=...&user=%7B...%7D&auth_date=1700000000&hash=abc...。 Telegram 文档中的算法:

  1. 1.将字符串解析为键值对(值经过 URL 解码)。
  2. 2.删除 hash 字段,并按键按字母顺序对剩余的对进行排序。
  3. 3.将它们连接成字符串 key=value,并用换行符 \n 分隔。这是数据检查字符串。
  4. 4.计算密钥:secret_key = HMAC_SHA256(key = "WebAppData", message = bot_token)。
  5. 5.计算HMAC_SHA256(key = secret_key, message = data_check_string)并转换为十六进制。
  6. 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 - 它在同一文档中进行了描述。

Обсуждение (0)

Ещё на vbcd4u.com