Telegram Mini App auf Next.js 15: serverseitige initData-Verifizierung über HMAC-SHA256
Warum Sie dem Kunden nicht vertrauen können
In der Mini-App ist das Objekt window.Telegram.WebApp.initDataUnsafe mit dem Feld user verfügbar. Es ist bequem, einen Namen anzuzeigen, aber für die Autorisierung ist es nutzlos: Jeder kann die Seite in einem normalen Browser öffnen und einen beliebigen id ersetzen. Sie können nur der Zeichenfolge Telegram.WebApp.initData vertrauen, und zwar erst, nachdem der Server seine Signatur mit dem Token Ihres Bots überprüft hat.
Verifizierungsalgorithmus
initData – eine Zeichenfolge im Abfragezeichenfolgenformat: query_id=...&user=%7B...%7D&auth_date=1700000000&hash=abc.... Algorithmus aus der Telegram-Dokumentation:
- 1.Analysieren Sie die Zeichenfolge in Schlüssel-Wert-Paare (die Werte werden URL-dekodiert).
- 2.Entfernen Sie das Feld
hashund sortieren Sie die verbleibenden Paare nach Schlüssel in alphabetischer Reihenfolge. - 3.Verketten Sie sie zu einer Zeichenfolge
key=value, getrennt durch ein Zeilenumbruchzeichen\n. Dies ist eine Datenprüfzeichenfolge. - 4.Berechnen Sie den geheimen Schlüssel:
secret_key = HMAC_SHA256(key = "WebAppData", message = bot_token). - 5.Berechnen Sie
HMAC_SHA256(key = secret_key, message = data_check_string)und konvertieren Sie ihn in Hex. - 6.Vergleichen Sie mit
hash. Überprüfen Sie außerdem, dassauth_datenicht zu alt ist.
Schritt 4 ist die Hauptursache für Fehler: Die Zeile "WebAppData" ist der Schlüssel und das Bot-Token ist die Nachricht. Wenn Sie sie verwechseln, wird die Signatur nie übereinstimmen.
Implementierung
// 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"),
};
}Bitte beachten Sie: Nur hash ist ausgeschlossen. Erstellen Sie keine Liste „bekannter“ Felder manuell – Telegram fügt neue Felder zu initData hinzu und der Hardcode unterbricht die Prüfung nach dem nächsten Client-Update.
Übertragung vom Kunden
"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}` },
});
}Die Zeichenfolge muss unverändert übertragen werden, ohne Neucodierung. Wenn man es zunächst in einen Gegenstand verwandelt und dann wieder zusammensetzt, ändern sich die Reihenfolge und die Abschirmung.
Routenhandler und Sitzung
// 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 ist cookies() asynchron, also await. sameSite: "none" wird benötigt, da die Mini-App in einem eingebetteten WebView geöffnet wird und dies in einigen Clients als Drittanbieterkontext betrachtet wird. Eine Alternative zu Cookies besteht darin, initData bei jeder Anfrage zu überprüfen: Dies ist einfacher und erfordert keinen Sitzungsspeicher, ist jedoch durch die Aktualität von auth_date begrenzt.
Wenn Sie Edge Runtime benötigen
node:crypto ist in Edge nicht verfügbar. Dieselbe Logik bei 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) -> hexVergleichen Sie in dieser Version Hex-Zeichenfolgen in konstanter Zeit (Schleife mit XOR über alle Zeichen) und nicht über ===.
Debuggen eines nicht übereinstimmenden Hashs
- Nehmen Sie
initDatavon einem echten Client und überprüfen Sie es mit einer Funktion in einem separaten Skript. Auf diese Weise trennen Sie den Algorithmusfehler vom Transportfehler. - Stellen Sie sicher, dass der Token dem Bot gehört, über den die Mini-App geöffnet wird. Die Test- und Kampfbots haben unterschiedliche Token.
– Überprüfen Sie, ob der Proxy oder das Framework den langen Header abschneidet.
- Wenn in den Protokollen während der Berechnung
%7Bim Wert vonuserangezeigt wird, bedeutet dies, dass Sie die Werte nicht dekodiert haben.URLSearchParamserledigt dies selbst.
Wenn es nicht reicht
Die initData-Prüfung bestätigt, dass die Daten von Telegram für Ihren Bot ausgegeben wurden, bietet aber keinen Schutz vor der Wiederverwendung der abgefangenen Zeichenfolge während maxAgeSec. Reduzieren Sie bei Geldtransaktionen das Fenster und verknüpfen Sie die Aktionen mit der Serversitzung. Wenn Sie Daten ohne Zugriff auf den Bot-Token überprüfen müssen (z. B. auf der Partnerseite), verfügt Telegram über einen separaten Mechanismus mit dem Feld signature und dem öffentlichen Schlüssel Ed25519 – dieser wird in derselben Dokumentation beschrieben.