Aplicación Telegram Mini en Next.js 15: verificación initData del lado del servidor a través de HMAC-SHA256
Por qué no puedes confiar en el cliente
En Mini App, el objeto window.Telegram.WebApp.initDataUnsafe con el campo user está disponible. Es conveniente usarlo para mostrar un nombre, pero es inútil para la autorización: cualquiera puede abrir la página en un navegador normal y sustituirlo por un [[VB_6_CODE] arbitrario. Solo puedes confiar en la cadena Telegram.WebApp.initData, y solo después de que el servidor verifique su firma con el token de tu bot.
Algoritmo de verificación
initData - una cadena en el formato de cadena de consulta: query_id=...&user=%7B...%7D&auth_date=1700000000&hash=abc.... Algoritmo de la documentación de Telegram:
- 1.Analice la cadena en pares clave-valor (los valores están decodificados en URL).
- 2.Elimine el campo
hashy ordene los pares restantes por clave en orden alfabético. - 3.Concatenarlos en una cadena
key=value, separados por un carácter de nueva línea\n. Esta es una cadena de verificación de datos. - 4.Calcule la clave secreta:
secret_key = HMAC_SHA256(key = "WebAppData", message = bot_token). - 5.Calcule
HMAC_SHA256(key = secret_key, message = data_check_string)y conviértalo a hexadecimal. - 6.Comparar con
hash. Además, verifique queauth_dateno sea demasiado antiguo.
El paso 4 es el lugar principal de los errores: la línea "WebAppData" es la clave y el token del bot es el mensaje. Si se mezclan, la firma nunca coincidirá.
Implementación
// 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"),
};
}Tenga en cuenta: solo se excluye hash. No compile una lista de campos "conocidos" manualmente: Telegram agrega nuevos campos a initData y el código anulará la verificación después de la próxima actualización del cliente.
Transferencia desde cliente
"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}` },
});
}La cadena debe transmitirse tal cual, sin volver a codificarla. Si primero lo conviertes en un objeto y luego lo vuelves a armar, el orden y el blindaje cambiarán.
Controlador de ruta y sesió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 });
}En Next.js 15, cookies() es asíncrono, por lo que await. sameSite: "none" es necesario porque la mini aplicación se abre en un WebView integrado y, en algunos clientes, esto se considera un contexto de terceros. Una alternativa a las cookies es verificar initData en cada solicitud: esto es más simple y no requiere almacenamiento de sesión, pero está limitado por la frescura de auth_date.
Si necesita Edge Runtime
node:crypto no está disponible en Edge. La misma lógica en 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) -> hexEn esta versión, compare cadenas hexadecimales en tiempo constante (bucle con XOR sobre todos los caracteres) y no a través de ===.
Depurando un hash no coincidente
- Tome
initDatade un cliente real y verifíquelo con una función en un script separado; de esta manera separará el error del algoritmo del error de transporte. - Asegúrate de que el token pertenezca al bot a través del cual se abre la Mini App. Los robots de prueba y de combate tienen fichas diferentes.
- Verifique si el proxy o el marco están cortando el encabezado largo.
- Si los registros muestran
%7Ben el valor deuserdurante el cálculo, significa que no decodificaste los valores.URLSearchParamslo hace él mismo.
Cuando no es suficiente
La verificación initData confirma que los datos fueron emitidos por Telegram para su bot, pero no protege contra la reutilización de la cadena interceptada durante maxAgeSec. Para transacciones de dinero, reduzca la ventana y vincule las acciones a la sesión del servidor. Si necesita verificar datos sin acceso al token del bot (por ejemplo, del lado del socio), Telegram tiene un mecanismo separado con el campo signature y la clave pública Ed25519; se describe en la misma documentación.