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

Aplikasi Telegram Mini di Next.js 15: verifikasi initData sisi server melalui HMAC-SHA256

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

Mengapa Anda tidak dapat mempercayai klien

Di Aplikasi Mini, objek window.Telegram.WebApp.initDataUnsafe dengan kolom user tersedia. Lebih mudah digunakan untuk menampilkan nama, tetapi tidak ada gunanya untuk otorisasi: siapa pun dapat membuka halaman di browser biasa dan mengganti id sewenang-wenang. Anda hanya dapat mempercayai string Telegram.WebApp.initData, dan hanya setelah server memverifikasi tanda tangannya dengan token bot Anda.

Algoritma verifikasi

initData - string dalam format string kueri: query_id=...&user=%7B...%7D&auth_date=1700000000&hash=abc.... Algoritma dari dokumentasi Telegram:

  1. 1.Parsing string menjadi pasangan nilai kunci (nilainya didekodekan oleh URL).
  2. 2.Hapus kolom hash dan urutkan pasangan yang tersisa berdasarkan kunci dalam urutan abjad.
  3. 3.Gabungkan keduanya menjadi string key=value, dipisahkan dengan karakter baris baru \n. Ini adalah string pemeriksaan data.
  4. 4.Hitung kunci rahasia: secret_key = HMAC_SHA256(key = "WebAppData", message = bot_token).
  5. 5.Hitung HMAC_SHA256(key = secret_key, message = data_check_string) dan konversikan ke hex.
  6. 6.Bandingkan dengan hash. Selain itu, periksa apakah auth_date tidak terlalu lama.

Langkah 4 adalah tempat utama kesalahan: baris "WebAppData" adalah kuncinya, dan token bot adalah pesannya. Jika tercampur aduk maka tanda tangannya tidak akan pernah cocok.

Implementasi

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

Harap diperhatikan: hanya hash yang dikecualikan. Jangan mengkompilasi daftar kolom "yang diketahui" secara manual - Telegram menambahkan kolom baru ke initData, dan hardcode akan membatalkan pemeriksaan setelah pembaruan klien berikutnya.

Transfer dari klien

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

String harus dikirimkan apa adanya, tanpa pengkodean ulang. Jika Anda mengubahnya menjadi sebuah objek terlebih dahulu lalu menyatukannya kembali, tatanan dan pelindungnya akan berubah.

Pengendali Rute dan sesi

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

Di Next.js 15, cookies() tidak sinkron, jadi await. sameSite: "none" diperlukan karena Aplikasi Mini terbuka di WebView yang tertanam, dan di beberapa klien ini dianggap sebagai konteks pihak ketiga. Alternatif untuk cookie adalah dengan memeriksa initData pada setiap permintaan: ini lebih sederhana dan tidak memerlukan penyimpanan sesi, namun dibatasi oleh kesegaran auth_date.

Jika Anda membutuhkan Edge Runtime

node:crypto tidak tersedia di Edge. Logika yang sama di 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

Dalam versi ini, bandingkan string hex dalam waktu konstan (loop dengan XOR pada semua karakter), dan bukan melalui ===.

Men-debug hash yang tidak cocok

  • Ambil initData dari klien nyata dan periksa dengan fungsi dalam skrip terpisah - dengan cara ini Anda akan memisahkan kesalahan algoritma dari kesalahan transportasi.
  • Pastikan token milik bot yang membuka Aplikasi Mini. Bot uji dan bot tempur memiliki token yang berbeda.
  • Periksa apakah proxy atau kerangka kerja memotong header panjang.
  • Jika log menunjukkan %7B dalam nilai user selama perhitungan, itu berarti Anda tidak memecahkan kode nilainya. URLSearchParams melakukan ini sendiri.

Ketika itu tidak cukup

Pemeriksaan initData mengonfirmasi bahwa data dikeluarkan oleh Telegram untuk bot Anda, namun tidak melindungi terhadap penggunaan kembali string yang disadap selama maxAgeSec. Untuk transaksi uang, kurangi jendela dan ikat tindakan ke sesi server. Jika Anda perlu memeriksa data tanpa akses ke token bot (misalnya, di pihak mitra), Telegram memiliki mekanisme terpisah dengan bidang signature dan kunci publik Ed25519 - dijelaskan dalam dokumentasi yang sama.

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

Ещё на vbcd4u.com