Telegram Mini App su Next.js 15: verifica initData lato server tramite HMAC-SHA256
Perché non puoi fidarti del cliente
Nella Mini App è disponibile l'oggetto window.Telegram.WebApp.initDataUnsafe con il campo user. È comodo da usare per visualizzare un nome, ma è inutile per l'autorizzazione: chiunque può aprire la pagina in un normale browser e sostituire un id arbitrario. Puoi fidarti solo della stringa Telegram.WebApp.initData e solo dopo che il server ha verificato la sua firma con il token del tuo bot.
Algoritmo di verifica
initData - una stringa nel formato della stringa di query: query_id=...&user=%7B...%7D&auth_date=1700000000&hash=abc.... Algoritmo dalla documentazione di Telegram:
- 1.Analizzare la stringa in coppie chiave-valore (i valori sono decodificati tramite URL).
- 2.Rimuovere il campo
hashe ordinare le coppie rimanenti per chiave in ordine alfabetico. - 3.Concatenarli in una stringa
key=value, separata da un carattere di nuova riga\n. Questa è la stringa di controllo dei dati. - 4.Calcolare la chiave segreta:
secret_key = HMAC_SHA256(key = "WebAppData", message = bot_token). - 5.Calcola
HMAC_SHA256(key = secret_key, message = data_check_string)e converti in esadecimale. - 6.Confronta con
hash. Inoltre, controlla cheauth_datenon sia troppo vecchio.
Il passaggio 4 è il luogo principale degli errori: la riga "WebAppData" è la chiave e il token del bot è il messaggio. Se li confondi, la firma non corrisponderà mai.
Implementazione
// 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"),
};
}Nota: solo hash è escluso. Non compilare manualmente un elenco di campi "conosciuti": Telegram aggiunge nuovi campi a initData e l'hardcode interromperà il controllo dopo il prossimo aggiornamento del client.
Trasferimento dal cliente
[[VB_1_CODICE]]
La stringa deve essere trasmessa così com'è, senza ricodifica. Se prima lo trasformi in un oggetto e poi lo rimetti insieme, l'ordine e la schermatura cambieranno.
Gestore del percorso e sessione
[[VB_2_CODICE]]
In Next.js 15, cookies() è asincrono, quindi await. sameSite: "none" è necessario perché la Mini App si apre in un WebView incorporato e in alcuni client questo è considerato un contesto di terze parti. Un'alternativa ai cookie è controllare initData ad ogni richiesta: questo è più semplice e non richiede la memorizzazione della sessione, ma è limitato dalla freschezza di auth_date.
Se hai bisogno di Edge Runtime
node:crypto non è disponibile in Edge. Stessa logica su Web Crypto:
[[VB_3_CODICE]]
In questa versione, confronta le stringhe esadecimali in tempo costante (loop con XOR su tutti i caratteri) e non tramite ===.
Debug di un hash non corrispondente
- Prendi
initDatada un client reale e controllalo con una funzione in uno script separato: in questo modo separerai l'errore dell'algoritmo dall'errore di trasporto. - Assicurati che il token appartenga al bot attraverso il quale viene aperta la Mini App. I robot di test e di combattimento hanno token diversi.
- Controlla se il proxy o il framework stanno tagliando l'intestazione lunga.
- Se i registri mostrano
%7Bnel valore diuserdurante il calcolo, significa che non hai decodificato i valori.URLSearchParamslo fa da solo.
##Quando non basta
Il controllo initData conferma che i dati sono stati emessi da Telegram per il tuo bot, ma non protegge dal riutilizzo della stringa intercettata durante maxAgeSec. Per le transazioni monetarie, riduci la finestra e collega le azioni alla sessione del server. Se hai bisogno di controllare i dati senza accedere al token del bot (ad esempio, dal lato del partner), Telegram ha un meccanismo separato con il campo signature e la chiave pubblica Ed25519 - è descritto nella stessa documentazione.