Next.js 15 の Telegram Mini アプリ: HMAC-SHA256 によるサーバー側の initData 検証
クライアントを信頼できない理由
ミニアプリでは、user フィールドを持つ window.Telegram.WebApp.initDataUnsafe オブジェクトが利用可能です。名前を表示するために使用すると便利ですが、認証には役に立ちません。誰でも通常のブラウザでページを開いて、任意の id を置き換えることができます。文字列 Telegram.WebApp.initData は、サーバーがボットのトークンでその署名を検証した後にのみ信頼できます。
検証アルゴリズム
initData - クエリ文字列形式の文字列: query_id=...&user=%7B...%7D&auth_date=1700000000&hash=abc...。 Telegram ドキュメントのアルゴリズム:
- 1.文字列をキーと値のペアに解析します (値は URL デコードされます)。
- 2.
hashフィールドを削除し、残りのペアをキーごとにアルファベット順に並べ替えます。 - 3.これらを文字列
key=valueに連結し、改行文字\nで区切ります。これはデータチェック文字列です。 - 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" が必要なのは、ミニアプリが埋め込み WebView で開き、一部のクライアントではこれがサードパーティ コンテキストとみなされるためです。 Cookie の代わりに、リクエストごとに initData をチェックする方法があります。これはより簡単でセッション ストレージを必要としませんが、auth_date の鮮度によって制限されます。
Edge ランタイムが必要な場合
node:crypto は Edge では使用できません。 Web 暗号化でも同じロジック:
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このバージョンでは、=== を介さずに、定数時間で 16 進文字列を比較します (すべての文字の XOR によるループ)。
不一致のハッシュのデバッグ
- 実際のクライアントから
initDataを取得し、別のスクリプトの関数でチェックします。これにより、アルゴリズム エラーをトランスポート エラーから分離できます。 - トークンがミニアプリを開くボットに属していることを確認してください。テストボットと戦闘ボットは異なるトークンを持っています。
- プロキシまたはフレームワークが長いヘッダーを切り取っているかどうかを確認します。
- 計算中にログに
userの値に%7Bが表示された場合は、値がデコードされていないことを意味します。URLSearchParams自体がこれを行います。
足りないときは
initData チェックは、データがボット用に Telegram によって発行されたことを確認しますが、maxAgeSec 中に傍受された文字列の再利用を防ぐことはできません。金銭取引の場合は、ウィンドウを縮小し、アクションをサーバー セッションに関連付けます。ボット トークンにアクセスせずにデータをチェックする必要がある場合 (たとえば、パートナー側)、Telegram には signature フィールドと公開キー Ed25519 を使用した別のメカニズムがあり、同じドキュメントで説明されています。