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

Telegram Mini App su Next.js 15: verifica initData lato server tramite HMAC-SHA256

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

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. 1.Analizzare la stringa in coppie chiave-valore (i valori sono decodificati tramite URL).
  2. 2.Rimuovere il campo hash e ordinare le coppie rimanenti per chiave in ordine alfabetico.
  3. 3.Concatenarli in una stringa key=value, separata da un carattere di nuova riga \n. Questa è la stringa di controllo dei dati.
  4. 4.Calcolare la chiave segreta: secret_key = HMAC_SHA256(key = "WebAppData", message = bot_token).
  5. 5.Calcola HMAC_SHA256(key = secret_key, message = data_check_string) e converti in esadecimale.
  6. 6.Confronta con hash. Inoltre, controlla che auth_date non 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 initData da 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 %7B nel valore di user durante il calcolo, significa che non hai decodificato i valori. URLSearchParams lo 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.

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

Ещё на vbcd4u.com