Next.js 15의 Telegram Mini 앱: HMAC-SHA256을 통한 서버 측 initData 확인
고객을 믿을 수 없는 이유
Mini App에서는 user 필드가 있는 window.Telegram.WebApp.initDataUnsafe 객체를 사용할 수 있습니다. 이름을 표시하는 데 사용하면 편리하지만 인증에는 쓸모가 없습니다. 누구나 일반 브라우저에서 페이지를 열고 임의의 id로 대체할 수 있습니다. Telegram.WebApp.initData 문자열만 신뢰할 수 있으며 서버가 봇의 토큰으로 서명을 확인한 후에만 가능합니다.
검증 알고리즘
initData - 쿼리 문자열 형식의 문자열: query_id=...&user=%7B...%7D&auth_date=1700000000&hash=abc.... 텔레그램 문서의 알고리즘:
- 1.문자열을 키-값 쌍으로 구문 분석합니다(값은 URL로 디코딩됨).
- 2.
hash필드를 제거하고 나머지 쌍을 키별로 알파벳순으로 정렬합니다. - 3.이를 개행 문자
\n로 구분된 문자열key=value로 연결합니다. 이것은 데이터 확인 문자열입니다. - 4.비밀 키:
secret_key = HMAC_SHA256(key = "WebAppData", message = bot_token)를 계산합니다. - 5.
HMAC_SHA256(key = secret_key, message = data_check_string)를 계산하여 16진수로 변환합니다. - 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를 사용하는 별도의 메커니즘이 있습니다. 이는 동일한 문서에 설명되어 있습니다.