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

Telegram Mini-app op Next.js 15: initData-verificatie aan de serverzijde via HMAC-SHA256

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

Waarom je de klant niet kunt vertrouwen

In Mini App is het object window.Telegram.WebApp.initDataUnsafe met het veld user beschikbaar. Het is handig om een ​​naam weer te geven, maar het is nutteloos voor autorisatie: iedereen kan de pagina in een gewone browser openen en een willekeurige id vervangen. Je kunt de string Telegram.WebApp.initData alleen vertrouwen, en alleen nadat de server zijn handtekening heeft geverifieerd met het token van je bot.

Verificatie-algoritme

initData - een tekenreeks in het querytekenreeksformaat: query_id=...&user=%7B...%7D&auth_date=1700000000&hash=abc.... Algoritme uit Telegram-documentatie:

  1. 1.Parseer de tekenreeks in sleutel-waardeparen (de waarden zijn URL-gedecodeerd).
  2. 2.Verwijder het veld hash en sorteer de resterende paren op sleutel in alfabetische volgorde.
  3. 3.Voeg ze samen tot een string key=value, gescheiden door een newline-teken \n. Dit is een data-check-string.
  4. 4.Bereken de geheime sleutel: secret_key = HMAC_SHA256(key = "WebAppData", message = bot_token).
  5. 5.Bereken HMAC_SHA256(key = secret_key, message = data_check_string) en converteer naar hex.
  6. 6.Vergelijk met hash. Controleer bovendien of auth_date niet te oud is.

Stap 4 is de belangrijkste plaats van fouten: de regel "WebAppData" is de sleutel en het bottoken is het bericht. Haal ze door elkaar en de handtekening zal nooit overeenkomen.

Implementatie

// 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"),
  };
}

Let op: alleen hash is uitgesloten. Stel niet handmatig een lijst met “bekende” velden samen - Telegram voegt nieuwe velden toe aan initData, en de hardcode zal de controle verbreken na de volgende clientupdate.

Overdracht van klant

"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}` },
  });
}

De string moet worden verzonden zoals hij is, zonder hercodering. Als je er eerst een object van maakt en het vervolgens weer in elkaar zet, verandert de volgorde en afscherming.

Route-afhandelaar en sessie

// 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 });
}

In Next.js 15 is cookies() asynchroon, dus await. sameSite: "none" is nodig omdat de mini-app wordt geopend in een ingebedde WebView, en bij sommige clients wordt dit beschouwd als een context van derden. Een alternatief voor cookies is om bij elk verzoek initData te controleren: dit is eenvoudiger en vereist geen sessie-opslag, maar wordt beperkt door de versheid van auth_date.

Als je Edge Runtime nodig hebt

node:crypto is niet beschikbaar in Edge. Dezelfde logica op 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

Vergelijk in deze versie hexadecimale strings in constante tijd (lus met XOR over alle tekens), en niet via ===.

Foutopsporing in een niet-overeenkomende hash

  • Neem initData van een echte client en controleer het met een functie in een apart script - op deze manier scheidt u de algoritmefout van de transportfout.
  • Zorg ervoor dat het token bij de bot hoort waarmee de Mini App wordt geopend. De test- en gevechtsbots hebben verschillende tokens.
  • Controleer of de proxy of het raamwerk de lange header afsnijdt.
  • Als de logs tijdens de berekening %7B weergeven in de waarde van user, betekent dit dat u de waarden niet hebt gedecodeerd. URLSearchParams doet dit zelf.

Als het niet genoeg is

De initData-controle bevestigt dat de gegevens door Telegram voor uw bot zijn uitgegeven, maar beschermt niet tegen hergebruik van de onderschepte string tijdens maxAgeSec. Voor geldtransacties verkleint u de periode en koppelt u acties aan de serversessie. Als u gegevens moet controleren zonder toegang tot het bottoken (bijvoorbeeld aan de kant van de partner), heeft Telegram een ​​apart mechanisme met het veld signature en de openbare sleutel Ed25519 - dit wordt beschreven in dezelfde documentatie.

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

Ещё на vbcd4u.com