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

Aplikacja Telegram Mini w Next.js 15: weryfikacja initData po stronie serwera za pomocą HMAC-SHA256

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

Dlaczego nie możesz ufać klientowi

W Mini App dostępny jest obiekt window.Telegram.WebApp.initDataUnsafe z polem user. Wygodne jest wyświetlanie nazwy, ale bezużyteczne przy autoryzacji: każdy może otworzyć stronę w zwykłej przeglądarce i podstawić dowolny id. Możesz zaufać tylko ciągowi Telegram.WebApp.initData i dopiero wtedy, gdy serwer zweryfikuje swój podpis tokenem Twojego bota.

Algorytm weryfikacji

initData - ciąg znaków w formacie ciągu zapytania: query_id=...&user=%7B...%7D&auth_date=1700000000&hash=abc.... Algorytm z dokumentacji Telegramu:

  1. 1.Podziel ciąg znaków na pary klucz-wartość (wartości są dekodowane przy użyciu adresu URL).
  2. 2.Usuń pole hash i posortuj pozostałe pary według klucza w kolejności alfabetycznej.
  3. 3.Połącz je w ciąg key=value oddzielony znakiem nowej linii \n. To jest ciąg kontrolny danych.
  4. 4.Oblicz tajny klucz: secret_key = HMAC_SHA256(key = "WebAppData", message = bot_token).
  5. 5.Oblicz HMAC_SHA256(key = secret_key, message = data_check_string) i przekonwertuj na wartość szesnastkową.
  6. 6.Porównaj z hash. Dodatkowo sprawdź, czy auth_date nie jest za stary.

Krok 4 to główne miejsce błędów: linia "WebAppData" to klucz, a token bota to wiadomość. Pomieszaj je, a podpis nigdy nie będzie pasował.

Implementacja

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

Uwaga: wykluczony jest tylko hash. Nie twórz ręcznie listy „znanych” pól — Telegram dodaje nowe pola do initData, a kod sprzętowy złamie kontrolę po następnej aktualizacji klienta.

Transfer od klienta

[[VB_1_KOD]]

Ciąg musi zostać przesłany w niezmienionej postaci, bez ponownego kodowania. Jeśli najpierw zamienisz go w obiekt, a następnie złożysz z powrotem, kolejność i ekranowanie ulegną zmianie.

Obsługa tras i sesja

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

W Next.js 15 cookies() jest asynchroniczny, więc await. sameSite: "none" jest potrzebny, ponieważ Miniaplikacja otwiera się w osadzonym widoku WebView, a w niektórych klientach jest to uważane za kontekst strony trzeciej. Alternatywą dla plików cookie jest sprawdzanie initData przy każdym żądaniu: jest to prostsze i nie wymaga przechowywania sesji, ale jest ograniczone świeżością auth_date.

Jeśli potrzebujesz środowiska wykonawczego Edge

node:crypto nie jest dostępny w Edge. Ta sama logika w 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

W tej wersji porównuje się ciągi szesnastkowe w stałym czasie (pętla z XOR po wszystkich znakach), a nie poprzez ===.

Debugowanie niedopasowanego skrótu

  • Weź initData z prawdziwego klienta i sprawdź go funkcją w osobnym skrypcie - w ten sposób oddzielisz błąd algorytmu od błędu transportu.
  • Upewnij się, że token należy do bota, za pośrednictwem którego otwierana jest Miniaplikacja. Boty testowe i boty bojowe mają różne tokeny.
  • Sprawdź, czy serwer proxy lub framework odcina długi nagłówek.
  • Jeżeli podczas obliczeń logi pokazują %7B w wartości user, oznacza to, że wartości nie zostały zdekodowane. URLSearchParams robi to sam.

Kiedy to nie wystarczy

Sprawdzenie initData potwierdza, że dane zostały wydane przez Telegram dla Twojego bota, ale nie chroni przed ponownym wykorzystaniem przechwyconego ciągu podczas maxAgeSec. W przypadku transakcji pieniężnych zmniejsz okno i powiąż działania z sesją serwera. Jeżeli potrzebujesz sprawdzić dane bez dostępu do tokena bota (np. po stronie partnera), Telegram posiada osobny mechanizm z polem signature i kluczem publicznym Ed25519 - jest to opisane w tej samej dokumentacji.

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

Ещё на vbcd4u.com