fix(telegram): hash the Mini App message in the replay key and split verifyInitData

- The anti-replay cache is filled before the allowlist check and the route
  keyed it on the raw `${hash}:${message}`, so distinct large messages could
  grow process memory. buildMiniAppReplayKey stores a SHA-256 digest of the
  message instead, keeping each entry a fixed size.
- Split verifyInitData (cyclomatic 32 / cognitive 30 after the anti-replay
  change) into auth-date, replay and signature helpers for the complexity
  ratchets. Behavior is unchanged.

Refs #19833
This commit is contained in:
Rafa Martins
2026-11-18 20:56:37 -03:00
committed by diegosouzapw
parent a7cf21786f
commit bc24bb2403
3 changed files with 119 additions and 58 deletions

View File

@@ -27,7 +27,7 @@ import {
isTelegramUserAllowed,
isTelegramWebhookSecretConfigured,
} from "@/lib/telegram/config";
import { verifyInitData, parseInitData } from "@/lib/telegram/initData";
import { buildMiniAppReplayKey, verifyInitData, parseInitData } from "@/lib/telegram/initData";
import { proxyChat } from "@/lib/telegram/chatProxy";
import { formatTelegramGatewayError } from "@/lib/telegram/errorMessage";
import { resolveOmniRouteBaseUrl } from "@/shared/utils/resolveOmniRouteBaseUrl";
@@ -126,7 +126,7 @@ async function handleMiniAppRequest(initData: string, body: Record<string, unkno
// cache on (hash, message) would 401 a user who sends the same short message twice.
const antiReplay = process.env.TELEGRAM_INITDATA_ANTI_REPLAY === "true";
const parsed = parseInitData(initData);
const replayKey = `${parsed.hash ?? ""}:${message}`;
const replayKey = buildMiniAppReplayKey(parsed.hash ?? "", message);
if (!verifyInitData(initData, botToken, undefined, { antiReplay, replayKey })) {
return NextResponse.json({ ok: false, error: "Invalid initData signature" }, { status: 401 });
}

View File

@@ -12,7 +12,7 @@
* directly unit-testable. Never trust the client-side `initData` alone —
* verification MUST happen server-side.
*/
import { createHmac, timingSafeEqual } from "node:crypto";
import { createHash, createHmac, timingSafeEqual } from "node:crypto";
export interface VerifyInitDataOptions {
/**
@@ -75,6 +75,94 @@ export function parseInitData(initData: string): Record<string, string> {
return out;
}
function parseAuthDate(data: Record<string, string>): number | null {
const authDate = Number.parseInt(data["auth_date"] ?? "", 10);
return Number.isFinite(authDate) && authDate > 0 ? authDate : null;
}
/** Freshness check on auth_date (unix seconds), bounded in both the past and the future. */
function isAuthDateWithinBounds(
data: Record<string, string>,
maxAgeSec: number,
nowSec: number,
maxClockSkewSec: number | undefined
): boolean {
if (maxAgeSec <= 0) return true;
const authDate = parseAuthDate(data);
if (authDate === null) return false;
if (nowSec - authDate > maxAgeSec) return false;
return authDate - nowSec <= (maxClockSkewSec ?? maxAgeSec);
}
function isReplayed(replayKey: string, nowSec: number): boolean {
sweepReplayCache(nowSec);
const existingExpiry = replayCache.get(replayKey);
return existingExpiry !== undefined && existingExpiry > nowSec;
}
/** Remember a verified replay key until its initData expires. */
function rememberReplayKey(
replayKey: string,
data: Record<string, string>,
maxAgeSec: number,
nowSec: number
): void {
const ttl = maxAgeSec > 0 ? maxAgeSec : 24 * 60 * 60;
const expiresAt = (parseAuthDate(data) ?? nowSec) + ttl;
if (replayCache.size >= MAX_REPLAY_CACHE_SIZE) {
sweepReplayCache(nowSec);
if (replayCache.size >= MAX_REPLAY_CACHE_SIZE) {
const firstKey = replayCache.keys().next().value;
if (firstKey) replayCache.delete(firstKey);
}
}
replayCache.set(replayKey, expiresAt);
}
function hasValidSignature(
data: Record<string, string>,
providedHash: string,
botToken: string
): boolean {
// Rebuild the data-check string: sorted key=value pairs, excluding hash.
const pairs = Object.entries(data)
.filter(([k]) => k !== "hash")
.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
.map(([k, v]) => `${k}=${v}`);
const dataCheckString = pairs.join("\n");
// secret_key = HMAC_SHA256(key="WebAppData", bot_token)
const secretKey = createHmac("sha256", "WebAppData").update(botToken).digest();
// expected_hash = HMAC_SHA256(secret_key, dataCheckString) hex
const expectedHash = createHmac("sha256", secretKey).update(dataCheckString).digest("hex");
const provided = Buffer.from(providedHash, "utf8");
const expected = Buffer.from(expectedHash, "utf8");
if (provided.length !== expected.length) return false;
return timingSafeEqual(provided, expected);
}
function resolveVerifyOptions(providedHash: string, options?: VerifyInitDataOptions) {
return {
now: options?.nowSec ?? Math.floor(Date.now() / 1000),
maxClockSkewSec: options?.maxClockSkewSec,
antiReplay: options?.antiReplay ?? false,
replayKey: options?.replayKey ?? providedHash,
};
}
/**
* Replay-cache key for a Mini App request: the initData hash plus a SHA-256 digest of the
* message. The cache is filled before the allowlist check, so the key must stay a fixed size
* instead of retaining the raw, unbounded message (#19833).
*/
export function buildMiniAppReplayKey(initDataHash: string, message: string): string {
const messageDigest = createHash("sha256").update(message, "utf8").digest("hex");
return `${initDataHash}:${messageDigest}`;
}
/**
* Verify a Telegram WebApp initData string against the bot token.
*
@@ -95,63 +183,16 @@ export function verifyInitData(
const providedHash = data["hash"];
if (!providedHash) return false;
const now = options?.nowSec ?? Math.floor(Date.now() / 1000);
const { now, maxClockSkewSec, antiReplay, replayKey } = resolveVerifyOptions(
providedHash,
options
);
if (!isAuthDateWithinBounds(data, maxAgeSec, now, maxClockSkewSec)) return false;
if (antiReplay && isReplayed(replayKey, now)) return false;
// Freshness check on auth_date (unix seconds) - bounds both past and future.
if (maxAgeSec > 0) {
const authDate = Number.parseInt(data["auth_date"] ?? "", 10);
if (!Number.isFinite(authDate) || authDate <= 0) return false;
// Check past expiration
if (now - authDate > maxAgeSec) return false;
// Check future expiration (clock skew tolerance)
const maxFutureSkew = options?.maxClockSkewSec ?? maxAgeSec;
if (authDate - now > maxFutureSkew) return false;
}
// Anti-replay check
const antiReplay = options?.antiReplay ?? false;
const replayKey = options?.replayKey ?? providedHash;
if (antiReplay) {
sweepReplayCache(now);
const existingExpiry = replayCache.get(replayKey);
if (existingExpiry !== undefined && existingExpiry > now) {
return false;
}
}
// Rebuild the data-check string: sorted key=value pairs, excluding hash.
const pairs = Object.entries(data)
.filter(([k]) => k !== "hash")
.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
.map(([k, v]) => `${k}=${v}`);
const dataCheckString = pairs.join("\n");
// secret_key = HMAC_SHA256(key="WebAppData", bot_token)
const secretKey = createHmac("sha256", "WebAppData").update(botToken).digest();
// expected_hash = HMAC_SHA256(secret_key, dataCheckString) hex
const expectedHash = createHmac("sha256", secretKey).update(dataCheckString).digest("hex");
const provided = Buffer.from(providedHash, "utf8");
const expected = Buffer.from(expectedHash, "utf8");
if (provided.length !== expected.length) return false;
if (!timingSafeEqual(provided, expected)) return false;
if (!hasValidSignature(data, providedHash, botToken)) return false;
// Signature is valid. If anti-replay is active, store key until expiry.
if (antiReplay) {
const authDate = Number.parseInt(data["auth_date"] ?? "", 10);
const ttl = maxAgeSec > 0 ? maxAgeSec : 24 * 60 * 60;
const expiresAt = (Number.isFinite(authDate) && authDate > 0 ? authDate : now) + ttl;
if (replayCache.size >= MAX_REPLAY_CACHE_SIZE) {
sweepReplayCache(now);
if (replayCache.size >= MAX_REPLAY_CACHE_SIZE) {
const firstKey = replayCache.keys().next().value;
if (firstKey) replayCache.delete(firstKey);
}
}
replayCache.set(replayKey, expiresAt);
}
if (antiReplay) rememberReplayKey(replayKey, data, maxAgeSec, now);
return true;
}

View File

@@ -3,6 +3,7 @@ import assert from "node:assert/strict";
import { createHmac } from "node:crypto";
import {
buildMiniAppReplayKey,
clearInitDataReplayCache,
parseInitData,
verifyInitData,
@@ -169,3 +170,22 @@ test("verifyInitData supports custom replayKey to bind message and payload", ()
true
);
});
test("buildMiniAppReplayKey keeps the replay key a fixed size whatever the message length", () => {
// #19833 review: the replay cache is filled before the allowlist check, so the key must not
// retain the raw (unbounded) Mini App message.
const hash = "a".repeat(64);
const huge = "x".repeat(1_000_000);
const key = buildMiniAppReplayKey(hash, huge);
assert.ok(key.startsWith(`${hash}:`));
assert.equal(key.length, hash.length + 1 + 64);
assert.ok(!key.includes("xxxx"), "the raw message must not be part of the key");
assert.equal(key, buildMiniAppReplayKey(hash, huge), "same (hash, message) → same key");
assert.notEqual(key, buildMiniAppReplayKey(hash, `${huge}y`), "distinct messages stay distinct");
assert.notEqual(
key,
buildMiniAppReplayKey("b".repeat(64), huge),
"distinct initData stays distinct"
);
});