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
Открыть все обсуждения →

고객을 믿을 수 없는 이유

Mini App에서는 user 필드가 있는 window.Telegram.WebApp.initDataUnsafe 객체를 사용할 수 있습니다. 이름을 표시하는 데 사용하면 편리하지만 인증에는 쓸모가 없습니다. 누구나 일반 브라우저에서 페이지를 열고 임의의 id로 대체할 수 있습니다. Telegram.WebApp.initData 문자열만 신뢰할 수 있으며 서버가 봇의 토큰으로 서명을 확인한 후에만 가능합니다.

검증 알고리즘

initData - 쿼리 문자열 형식의 문자열: query_id=...&user=%7B...%7D&auth_date=1700000000&hash=abc.... 텔레그램 문서의 알고리즘:

  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)를 계산하여 16진수로 변환합니다.
  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"는 Mini App이 내장된 WebView에서 열리기 때문에 필요하며 일부 클라이언트에서는 이것이 타사 컨텍스트로 간주됩니다. 쿠키의 대안은 모든 요청에서 initData를 확인하는 것입니다. 이는 더 간단하고 세션 저장이 필요하지 않지만 auth_date의 최신성에 의해 제한됩니다.

Edge 런타임이 필요한 경우

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 루프)으로 16진수 문자열을 비교합니다.

일치하지 않는 해시 디버깅

  • 실제 클라이언트에서 initData를 가져와 별도의 스크립트에 있는 함수로 확인합니다. 이렇게 하면 알고리즘 오류와 전송 오류가 분리됩니다.
  • 토큰이 미니앱을 여는 봇에 속해 있는지 확인하세요. 테스트 로봇과 전투 로봇은 서로 다른 토큰을 가지고 있습니다.
  • 프록시나 프레임워크가 긴 헤더를 자르는지 확인하세요.
  • 계산 중에 로그에 user 값에 %7B가 표시되면 해당 값을 디코딩하지 않았다는 의미입니다. URLSearchParams는 이 작업을 자체적으로 수행합니다.

##부족할 때

initData 검사는 Telegram에서 봇을 위해 데이터가 발행되었는지 확인하지만 maxAgeSec 동안 가로채는 문자열의 재사용을 방지하지는 않습니다. 금전 거래의 경우 창을 줄이고 작업을 서버 세션에 연결합니다. 봇 토큰(예: 파트너 측)에 액세스하지 않고 데이터를 확인해야 하는 경우 Telegram에는 signature 필드와 공개 키 Ed25519를 사용하는 별도의 메커니즘이 있습니다. 이는 동일한 문서에 설명되어 있습니다.

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

Ещё на vbcd4u.com