fix: fail-fast guard TELEGRAM_CHUNK_SIZE_BYTES <= 19MB (Telegram getFile limit 20MB)

Chunk parts > 19MB are stored to Telegram but getFile cannot resolve files over 20MB ('Bad Request: file is too big'), making every part undownloadable (prod bug 2026-08-01: 48MB chunk -> download 500).

- src/env.ts: reject TELEGRAM_CHUNK_SIZE_BYTES > 19922944 at startup (log error + throw), default changed 20MB -> 19MB
- src/shared/utils/validation.ts: TELEGRAM_CHUNK_SIZE_MAX_BYTES constant; asSafeChunkSize now enforces the max at runtime (covers S3 multipart parts too)
- test/env.test.ts: unit tests + subprocess fail-fast tests (48MB rejected, 19MB accepted)
- test/helpers/setup-env.ts: pin safe chunk size so a stale .env can't break the suite
- .env.example + CLAUDE.md: document the 20MB getFile limit

src/env.ts

@@ -1,4 +1,5 @@
 import logger from './shared/logger/index';
+import { TELEGRAM_CHUNK_SIZE_MAX_BYTES } from './shared/utils/validation';
 
 interface AppConfig {
   /** All bot tokens merged from BOT_TOKENS (or BOT_TOKEN + ADDITIONAL_BOT_TOKENS fallback) */
@@ -107,6 +108,29 @@ const maskSecret = (value: string): string => {
 const maskDatabaseUrl = (value: string): string =>
   value.replace(/:\/\/([^:]+):([^@]+)@/, '://$1:***@');
 
+// Fail-fast guard for TELEGRAM_CHUNK_SIZE_BYTES: chunked uploads store every
+// part as a Telegram document and later resolve it via getFile, which only
+// supports files up to 20 MB ("Bad Request: file is too big" above that).
+// A chunk above the limit makes every part undownloadable — refuse to start
+// instead of failing on the first large-file download.
+const telegramChunkSizeBytes = parseNumber(
+  process.env.TELEGRAM_CHUNK_SIZE_BYTES,
+  TELEGRAM_CHUNK_SIZE_MAX_BYTES,
+);
+if (telegramChunkSizeBytes > TELEGRAM_CHUNK_SIZE_MAX_BYTES) {
+  logger.error(
+    `TELEGRAM_CHUNK_SIZE_BYTES=${telegramChunkSizeBytes} exceeds the maximum allowed chunk size ` +
+      `${TELEGRAM_CHUNK_SIZE_MAX_BYTES} bytes (${TELEGRAM_CHUNK_SIZE_MAX_BYTES / (1024 * 1024)} MB). ` +
+      'Telegram Bot API getFile cannot download files larger than 20 MB, so every stored part would ' +
+      'be undownloadable ("Bad Request: file is too big"). ' +
+      `Set TELEGRAM_CHUNK_SIZE_BYTES to ${TELEGRAM_CHUNK_SIZE_MAX_BYTES} or lower.`,
+  );
+  throw new Error(
+    `TELEGRAM_CHUNK_SIZE_BYTES=${telegramChunkSizeBytes} exceeds the maximum allowed chunk size ` +
+      `${TELEGRAM_CHUNK_SIZE_MAX_BYTES} bytes (${TELEGRAM_CHUNK_SIZE_MAX_BYTES / (1024 * 1024)} MB)`,
+  );
+}
+
 export const config: AppConfig = {
   botTokens: parseTokens(botTokensRaw),
   telegramBotConcurrency: parseNumber(process.env.TELEGRAM_BOT_CONCURRENCY, 1),
@@ -122,7 +146,7 @@ export const config: AppConfig = {
   batchMaxItems: parseNumber(process.env.BATCH_MAX_ITEMS, 20),
   batchMaxSizeBytes: parseNumber(process.env.BATCH_MAX_SIZE_BYTES, 500 * 1024 * 1024),
   maxRequestBodyBytes: parseNumber(process.env.MAX_REQUEST_BODY_BYTES, 2 * 1024 * 1024 * 1024),
-  telegramChunkSizeBytes: parseNumber(process.env.TELEGRAM_CHUNK_SIZE_BYTES, 20 * 1024 * 1024),
+  telegramChunkSizeBytes,
   compressChunkedUploads: process.env.COMPRESS_CHUNKED_UPLOADS !== 'false',
   chunkCompressionMinSizeBytes: parseNumber(process.env.CHUNK_COMPRESSION_MIN_SIZE_BYTES, 4096),
   adminApiToken: process.env.ADMIN_API_TOKEN || '',

src/shared/utils/validation.ts

@@ -1,13 +1,33 @@
+/**
+ * Maximum allowed chunk/part size in bytes for Telegram storage.
+ *
+ * Telegram Bot API `getFile` can only resolve files up to 20 MB; anything
+ * larger fails with "Bad Request: file is too big". Chunked uploads store
+ * each part as a Telegram document and later resolve it via `getFile`, so a
+ * part must never reach that limit. 19 MB (19922944 bytes) leaves a safety
+ * margin and is the value used in production (/etc/teleuploader/env).
+ */
+export const TELEGRAM_CHUNK_SIZE_MAX_BYTES = 19 * 1024 * 1024;
+
 /**
  * Validates a chunk size value and returns it as a safe integer.
  *
  * @param chunkSizeBytes - The desired chunk size in bytes.
- * @returns The same value if it is a positive safe integer.
- * @throws {Error} If the chunk size is not a safe positive integer.
+ * @returns The same value if it is a positive safe integer at or below
+ *   {@link TELEGRAM_CHUNK_SIZE_MAX_BYTES}.
+ * @throws {Error} If the chunk size is not a safe positive integer or exceeds
+ *   the Telegram `getFile` limit (with margin).
  */
 export const asSafeChunkSize = (chunkSizeBytes: number): number => {
   if (!Number.isSafeInteger(chunkSizeBytes) || chunkSizeBytes <= 0) {
     throw new Error('Invalid Telegram chunk size');
   }
+  if (chunkSizeBytes > TELEGRAM_CHUNK_SIZE_MAX_BYTES) {
+    throw new Error(
+      `Telegram chunk size ${chunkSizeBytes} exceeds the maximum allowed part size ` +
+        `${TELEGRAM_CHUNK_SIZE_MAX_BYTES} bytes (${TELEGRAM_CHUNK_SIZE_MAX_BYTES / (1024 * 1024)} MB). ` +
+        'Telegram getFile cannot download files larger than 20 MB, so such parts would be undownloadable.',
+    );
+  }
   return chunkSizeBytes;
 };