Next.js 15'teki Telegram Mini Uygulaması: HMAC-SHA256 aracılığıyla sunucu tarafı initData doğrulaması
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.Dizeyi anahtar/değer çiftlerine ayrıştırın (değerlerin kodu URL ile çözülür).
- 2.
hashalanını kaldırın ve kalan çiftleri anahtara göre alfabetik sıraya göre sıralayın. - 3.Bunları yeni satır karakteriyle
\nayırarak bir dizekey=valuehalinde birleştirin. Bu veri kontrol dizisidir. - 4.Gizli anahtarı hesaplayın:
secret_key = HMAC_SHA256(key = "WebAppData", message = bot_token). - 5.
HMAC_SHA256(key = secret_key, message = data_check_string)değerini hesaplayın ve hex'e dönüştürün. - 6.
hashile karşılaştırın. Ayrıcaauth_datekodunun ç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) -> hexBu 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
initDataalı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
userdeğerinde%7Bgösteriyorsa bu, değerlerin kodunu çözmediğiniz anlamına gelir.URLSearchParamsbunu 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.