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

Aplicación Telegram Mini en Next.js 15: verificación initData del lado del servidor a través de HMAC-SHA256

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

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. 1.Analice la cadena en pares clave-valor (los valores están decodificados en URL).
  2. 2.Elimine el campo hash y ordene los pares restantes por clave en orden alfabético.
  3. 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. 4.Calcule la clave secreta: secret_key = HMAC_SHA256(key = "WebAppData", message = bot_token).
  5. 5.Calcule HMAC_SHA256(key = secret_key, message = data_check_string) y conviértalo a hexadecimal.
  6. 6.Comparar con hash. Además, verifique que auth_date no 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) -> hex

En 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 initData de 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 %7B en el valor de user durante el cálculo, significa que no decodificaste los valores. URLSearchParams lo 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.

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

Ещё на vbcd4u.com