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

Next.js 15 жүйесіндегі Telegram Mini қолданбасы: HMAC-SHA256 арқылы серверлік initData тексеруі

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

Неліктен клиентке сенуге болмайды

Шағын қолданбада user өрісі бар window.Telegram.WebApp.initDataUnsafe нысаны қолжетімді. Бұл атауды көрсету үшін пайдалану ыңғайлы, бірақ авторизациялау үшін пайдасыз: кез келген адам бетті қарапайым браузерде ашып, еркін id ауыстыра алады. Сіз тек Telegram.WebApp.initData жолына сене аласыз және сервер оның қолтаңбасын бот белгісімен тексергеннен кейін ғана.

Тексеру алгоритмі

initData - сұрау жолы пішіміндегі жол: query_id=...&user=%7B...%7D&auth_date=1700000000&hash=abc.... Telegram құжаттамасынан алгоритм:

  1. 1.Жолды кілт-мән жұптарына талдаңыз (мәндер URL-декодталған).
  2. 2.hash өрісін алып тастаңыз және қалған жұптарды алфавиттік ретпен перне бойынша сұрыптаңыз.
  3. 3.Оларды жаңа жол таңбасы \n арқылы бөлінген key=value жолына біріктіріңіз. Бұл деректерді тексеру жолы.
  4. 4.Құпия кілтті есептеңіз: secret_key = HMAC_SHA256(key = "WebAppData", message = bot_token).
  5. 5.HMAC_SHA256(key = secret_key, message = data_check_string) есептеп, он алтылыққа түрлендіріңіз.
  6. 6.hash параметрімен салыстырыңыз. Оған қоса, auth_date тым ескі емес екенін тексеріңіз.

4-қадам – қателердің негізгі орны: "WebAppData" жолы – кілт, ал бот белгісі – хабарлама. Оларды араластырыңыз және қолтаңба ешқашан сәйкес келмейді.

Іске асыру

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

Назар аударыңыз: тек hash алынып тасталды. «Белгілі» өрістердің тізімін қолмен құрастырмаңыз - Telegram initData ішіне жаңа өрістерді қосады және клиенттің келесі жаңартуынан кейін қатты код тексеруді бұзады.

Клиенттен аудару

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

Жолды қайта кодтаусыз, сол күйінде жіберу керек. Егер сіз оны алдымен нысанға айналдырсаңыз, содан кейін қайта біріктірсеңіз, реті мен экрандауы өзгереді.

Маршрутты өңдеуші және сеанс

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

Next.js 15 ішінде cookies() асинхронды, сондықтан await. sameSite: "none" қажет, себебі Шағын қолданба ендірілген WebView ішінде ашылады және кейбір клиенттерде бұл үшінші тарап мәтінмәні ретінде қарастырылады. Cookie файлдарына балама әрбір сұрауда initData тексеру болып табылады: бұл оңайырақ және сеансты сақтауды қажет етпейді, бірақ auth_date жаңалығымен шектеледі.

Егер сізге Edge Runtime керек болса

node:crypto Edge қолданбасында қолжетімді емес. 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

Бұл нұсқада === арқылы емес, тұрақты уақытта (барлық таңбалар бойынша XOR бар цикл) он алтылық жолдарын салыстырыңыз.

Сәйкес келмейтін хэшті жөндеу

  • Нақты клиенттен initData алыңыз және оны бөлек сценарийдегі функциямен тексеріңіз - осылайша сіз алгоритм қатесін тасымалдау қателігінен ажыратасыз.
  • Токен шағын қолданба ашылатын ботқа тиесілі екеніне көз жеткізіңіз. Сынақ және жауынгерлік боттарда әртүрлі белгілер бар.
  • Прокси немесе жақтау ұзын тақырыпты кесіп жатқанын тексеріңіз.
  • Егер журналдар есептеу кезінде user мәнінде %7B көрсетсе, бұл мәндерді декодтамағаныңызды білдіреді. URLSearchParams мұны өзі жасайды.

Бұл жеткіліксіз болған кезде

initData тексеруі деректердің Telegram арқылы сіздің ботыңыз үшін шығарылғанын растайды, бірақ maxAgeSec кезінде ұсталған жолды қайта пайдаланудан қорғамайды. Ақша транзакциялары үшін терезені азайтып, әрекеттерді сервер сеансына байланыстырыңыз. Егер сізге бот токеніне қол жеткізбестен деректерді тексеру қажет болса (мысалы, серіктес жағында), Telegram-да signature өрісі және Ed25519 ашық кілті бар бөлек механизм бар - ол сол құжаттамада сипатталған.

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

Ещё на vbcd4u.com