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

Next.js 15'teki Telegram Mini Uygulaması: HMAC-SHA256 aracılığıyla sunucu tarafı initData doğrulaması

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

Müşteriye neden güvenemiyorsunuz?

Mini Uygulamada, user alanına sahip window.Telegram.WebApp.initDataUnsafe nesnesi mevcuttur. Bir adı görüntülemek için kullanılması uygundur, ancak yetkilendirme için faydası yoktur: Herkes sayfayı normal bir tarayıcıda açabilir ve yerine isteğe bağlı bir id koyabilir. Yalnızca Telegram.WebApp.initData dizesine güvenebilirsiniz ve yalnızca sunucu imzasını botunuzun belirteciyle doğruladıktan sonra güvenebilirsiniz.

Doğrulama algoritması

initData - sorgu dizesi biçiminde bir dize: query_id=...&user=%7B...%7D&auth_date=1700000000&hash=abc.... Telegram belgelerinden algoritma:

  1. 1.Dizeyi anahtar/değer çiftlerine ayrıştırın (değerlerin kodu URL ile çözülür).
  2. 2.hash alanını kaldırın ve kalan çiftleri anahtara göre alfabetik sıraya göre sıralayın.
  3. 3.Bunları yeni satır karakteriyle \n ayırarak bir dize key=value halinde birleştirin. Bu veri kontrol dizisidir.
  4. 4.Gizli anahtarı hesaplayın: secret_key = HMAC_SHA256(key = "WebAppData", message = bot_token).
  5. 5.HMAC_SHA256(key = secret_key, message = data_check_string) değerini hesaplayın ve hex'e dönüştürün.
  6. 6.hash ile karşılaştırın. Ayrıca auth_date kodunun çok eski olmadığını kontrol edin.

Adım 4, hataların ana yeridir: "WebAppData" satırı anahtardır ve bot jetonu mesajdır. Bunları karıştırırsanız imza asla eşleşmeyecektir.

Uygulama

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

Lütfen unutmayın: yalnızca hash hariçtir. "Bilinen" alanların listesini manuel olarak derlemeyin - Telegram, initData'a yeni alanlar ekler ve sabit kod, bir sonraki istemci güncellemesinden sonra kontrolü bozar.

İstemciden transfer

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

Dize, yeniden kodlama olmadan olduğu gibi iletilmelidir. Eğer onu önce bir nesneye çevirip sonra tekrar birleştirirseniz, düzen ve perdeleme değişecektir.

Rota İşleyicisi ve oturum

// 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'te, cookies() eşzamansızdır, dolayısıyla await. Mini Uygulama yerleşik bir Web Görünümünde açıldığından ve bazı istemcilerde bu üçüncü taraf bağlamı olarak değerlendirildiğinden sameSite: "none" gereklidir. Çerezlere bir alternatif, her istekte initData'u kontrol etmektir: bu daha basittir ve oturum depolaması gerektirmez, ancak auth_date'un güncelliğiyle sınırlıdır.

Edge Runtime'a ihtiyacınız varsa

node:crypto Edge'de mevcut değil. Web Crypto'da da aynı mantık:

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

Bu sürümde, onaltılık dizeleri === aracılığıyla değil, sabit zamanda (tüm karakterler üzerinde XOR ile döngü) karşılaştırın.

Eşleşmeyen karmada hata ayıklama

  • Gerçek bir istemciden initData alın ve ayrı bir komut dosyasındaki bir işlevle kontrol edin - bu şekilde algoritma hatasını aktarım hatasından ayıracaksınız.
  • Tokenın Mini Uygulamanın açıldığı bota ait olduğundan emin olun. Test ve savaş botlarının farklı jetonları vardır.
  • Proxy'nin veya çerçevenin uzun başlığı kesip kesmediğini kontrol edin.
  • Günlükler hesaplama sırasında user değerinde %7B gösteriyorsa bu, değerlerin kodunu çözmediğiniz anlamına gelir. URLSearchParams bunu kendisi yapıyor.

Yeterli olmadığında

initData kontrolü, verilerin Telegram tarafından botunuz için yayınlandığını doğrular, ancak maxAgeSec sırasında ele geçirilen dizenin yeniden kullanılmasına karşı koruma sağlamaz. Para işlemleri için pencereyi küçültün ve eylemleri sunucu oturumuna bağlayın. Bot jetonuna erişiminiz olmadan verileri kontrol etmeniz gerekiyorsa (örneğin, ortak tarafında), Telegram'ın signature alanı ve Ed25519 genel anahtarıyla ayrı bir mekanizması vardır - bu aynı belgelerde açıklanmıştır.

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

Ещё на vbcd4u.com