@openclaw/crabline 0.1.10 → 0.1.12

package/dist/src/servers/telegram.js

@@ -1,17 +1,26 @@
 import { createServer } from "node:http";
-import { randomBytes } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
+import { Buffer } from "node:buffer";
 import path from "node:path";
 import { CrablineError } from "../core/errors.js";
-import { adminAuthError, closeServer, drainRequestBody, formatUrlHost, hasAdminToken, InvalidJsonBodyError, isJsonObject, isLoopbackHost, jsonResponse, queryRecord, readBody, RequestBodyTooLargeError, writeResponse, } from "./http.js";
+import { adminAuthError, closeServer, drainRequestBody, formatUrlHost, hasAdminToken, InvalidJsonBodyError, isJsonObject, isJsonMediaType, isLoopbackHost, jsonResponse, queryRecord, readBody, RequestBodyTooLargeError, writeResponse, } from "./http.js";
 import { recordServerEvent } from "./recorder.js";
 import { resolveMaxPendingInboundEvents } from "./pending-events.js";
 import { postWebhookRequest, validateWebhookTarget, } from "./webhook-target.js";
+import { canonicalizeTelegramUsername, isTelegramUsernameChatId, TELEGRAM_BOT_USERNAME_PATTERN, TELEGRAM_NATIVE_CHAT_ID_MAX, telegramUsernameChatId, } from "./telegram-identity.js";
 const TELEGRAM_MAX_REQUEST_BODY_BYTES = 50 * 1024 * 1024;
+const TELEGRAM_MAX_MULTIPART_HEADER_BYTES = 16 * 1024;
+const TELEGRAM_MAX_MULTIPART_PARTS = 128;
+const TELEGRAM_MAX_MULTIPART_TEXT_BYTES = 1024 * 1024;
 const TELEGRAM_WEBHOOK_MAX_BACKOFF_EXPONENT = 5;
 const TELEGRAM_WEBHOOK_RETRY_BASE_MS = 100;
 const TELEGRAM_WEBHOOK_DELIVERY_TIMEOUT_MS = 3_000;
 const MAX_ACTIVE_TELEGRAM_WEBHOOK_VALIDATIONS = 8;
-const TELEGRAM_CHAT_USERNAME_PATTERN = /^@[A-Za-z][A-Za-z0-9_]{3,31}$/u;
+const TELEGRAM_WEBHOOK_SECRET_PATTERN = /^[A-Za-z0-9_-]{1,256}(?![\s\S])/u;
+const TELEGRAM_MAX_TEXT_LENGTH = 4096;
+const TELEGRAM_MAX_CAPTION_LENGTH = 1024;
+const TELEGRAM_HTML_TAG_PATTERN = /<\/?(?:a|b|blockquote|code|del|em|i|ins|pre|s|span|strike|strong|tg-emoji|tg-spoiler|tg-time|u)(?:\s+[^<>]*)?>/giu;
+const TELEGRAM_HTML_ENTITY_PATTERN = /&(?:#\d+|#x[\da-f]+|amp|gt|lt|quot);/giu;
 const TELEGRAM_SEND_METHODS = new Set([
     "sendanimation",
     "sendaudio",
@@ -58,6 +67,27 @@ const TELEGRAM_UNSUPPORTED_UPDATE_FIELDS = [
     "removed_chat_boost",
     "shipping_query",
 ];
+const TELEGRAM_NEW_MESSAGE_UPDATE_FIELDS = ["business_message", "channel_post", "message"];
+const TELEGRAM_MESSAGE_REFERENCE_FIELDS = [
+    "edited_business_message",
+    "edited_channel_post",
+    "edited_message",
+];
+const TELEGRAM_MESSAGE_UPDATE_FIELDS = [
+    ...TELEGRAM_NEW_MESSAGE_UPDATE_FIELDS,
+    ...TELEGRAM_MESSAGE_REFERENCE_FIELDS,
+];
+const TELEGRAM_CHAT_UPDATE_FIELDS = [
+    "chat_boost",
+    "chat_join_request",
+    "chat_member",
+    "deleted_business_messages",
+    "message_reaction",
+    "message_reaction_count",
+    "my_chat_member",
+    "removed_chat_boost",
+];
+const TELEGRAM_MULTIPART_FILE = Symbol("telegramMultipartFile");
 function telegramOk(result) {
     return jsonResponse({ ok: true, result });
 }
@@ -65,13 +95,17 @@ function telegramError(description, status = 400) {
     return jsonResponse({ description, error_code: status, ok: false }, status);
 }
 async function parseRequestBody(request) {
+    const contentType = request.headers["content-type"] ?? "";
+    const contentTypes = Array.isArray(contentType) ? contentType : [contentType];
+    const multipartType = contentTypes.find((entry) => entry.toLowerCase().includes("multipart/form-data"));
+    if (multipartType) {
+        return await parseMultipartFormDataRequest(request, multipartType);
+    }
     const body = await readBody(request, TELEGRAM_MAX_REQUEST_BODY_BYTES);
     if (body.length === 0) {
         return {};
     }
-    const contentType = request.headers["content-type"] ?? "";
-    const contentTypes = Array.isArray(contentType) ? contentType : [contentType];
-    if (contentTypes.some((entry) => entry.toLowerCase().includes("json"))) {
+    if (contentTypes.some(isJsonMediaType)) {
         try {
             return JSON.parse(body.toString("utf8"));
         }
@@ -79,30 +113,435 @@ async function parseRequestBody(request) {
             throw new InvalidJsonBodyError(error);
         }
     }
-    const multipartType = contentTypes.find((entry) => entry.toLowerCase().includes("multipart/form-data"));
-    if (multipartType) {
-        return await parseMultipartFormDataBody(body, multipartType);
-    }
     const params = new URLSearchParams(body.toString("utf8"));
     return Object.fromEntries(params.entries());
 }
-async function parseMultipartFormDataBody(body, contentType) {
-    let form;
+function invalidTelegramMultipartBody(message) {
+    return new InvalidJsonBodyError(new Error(message));
+}
+function parseTelegramMimeParameters(value, options = {}) {
+    const separator = value.indexOf(";");
+    const type = value
+        .slice(0, separator < 0 ? value.length : separator)
+        .trim()
+        .toLowerCase();
+    const parameters = new Map();
+    let index = separator < 0 ? value.length : separator + 1;
+    while (index < value.length) {
+        while (index < value.length && /[\t ;]/u.test(value[index] ?? "")) {
+            index += 1;
+        }
+        if (index >= value.length) {
+            break;
+        }
+        const nameStart = index;
+        while (index < value.length && /[!#$%&'*+\-.^_`|~0-9A-Za-z]/u.test(value[index] ?? "")) {
+            index += 1;
+        }
+        const name = value.slice(nameStart, index).toLowerCase();
+        while (index < value.length && /[\t ]/u.test(value[index] ?? "")) {
+            index += 1;
+        }
+        if (!name || value[index] !== "=") {
+            throw invalidTelegramMultipartBody("Multipart header contains a malformed parameter.");
+        }
+        index += 1;
+        while (index < value.length && /[\t ]/u.test(value[index] ?? "")) {
+            index += 1;
+        }
+        let parameterValue = "";
+        let quoted = false;
+        if (value[index] === '"') {
+            quoted = true;
+            index += 1;
+            let closed = false;
+            while (index < value.length) {
+                const character = value[index];
+                index += 1;
+                if (character === "\\" && options.decodeQuotedPairs) {
+                    if (index >= value.length) {
+                        break;
+                    }
+                    const quotedCharacter = value[index];
+                    if (quotedCharacter === "\r" || quotedCharacter === "\n") {
+                        break;
+                    }
+                    parameterValue += quotedCharacter;
+                    index += 1;
+                }
+                else if (character === '"') {
+                    closed = true;
+                    break;
+                }
+                else if (character === "\r" || character === "\n") {
+                    break;
+                }
+                else {
+                    parameterValue += character;
+                }
+            }
+            if (!closed) {
+                throw invalidTelegramMultipartBody("Multipart header contains an unterminated quote.");
+            }
+            while (index < value.length && /[\t ]/u.test(value[index] ?? "")) {
+                index += 1;
+            }
+            if (index < value.length && value[index] !== ";") {
+                throw invalidTelegramMultipartBody("Multipart header contains trailing parameter data.");
+            }
+        }
+        else {
+            const parameterStart = index;
+            while (index < value.length && value[index] !== ";") {
+                if (value[index] === "\r" || value[index] === "\n") {
+                    throw invalidTelegramMultipartBody("Multipart header contains a line break.");
+                }
+                index += 1;
+            }
+            parameterValue = value.slice(parameterStart, index).trim();
+        }
+        parameters.set(name, { quoted, value: parameterValue });
+        if (value[index] === ";") {
+            index += 1;
+        }
+    }
+    return { parameters, type };
+}
+function parseTelegramMultipartBoundary(contentType) {
+    const parsed = parseTelegramMimeParameters(contentType, { decodeQuotedPairs: true });
+    const boundary = parsed.parameters.get("boundary")?.value;
+    if (parsed.type !== "multipart/form-data" ||
+        !boundary ||
+        boundary.length > 70 ||
+        boundary.endsWith(" ") ||
+        !/^[0-9A-Za-z'()+_,./:=? -]+$/u.test(boundary)) {
+        throw invalidTelegramMultipartBody("Multipart boundary is missing or invalid.");
+    }
+    return Buffer.from(`--${boundary}`, "ascii");
+}
+function decodeTelegramMultipartParameter(parameter) {
+    return parameter.quoted
+        ? parameter.value.replace(/%0A/giu, "\n").replace(/%0D/giu, "\r").replace(/%22/giu, '"')
+        : parameter.value;
+}
+function decodeTelegramMultipartExtendedParameter(parameter) {
+    const extended = /^([^']*)'[^']*'(.*)$/u.exec(parameter.value);
+    if (!extended) {
+        return decodeTelegramMultipartParameter(parameter);
+    }
+    const charset = extended[1]?.toLowerCase();
+    if (charset !== "utf-8" && charset !== "us-ascii") {
+        return decodeTelegramMultipartParameter(parameter);
+    }
     try {
-        form = await new Request("http://localhost", {
-            body,
-            headers: { "content-type": contentType },
-            method: "POST",
-        }).formData();
+        return decodeURIComponent(extended[2] ?? "");
     }
-    catch (error) {
-        throw new InvalidJsonBodyError(error);
+    catch {
+        return extended[2] ?? "";
+    }
+}
+function parseTelegramMultipartDisposition(headerBlock) {
+    let contentDisposition;
+    for (const line of headerBlock.toString("utf8").split("\r\n")) {
+        const separator = line.indexOf(":");
+        if (separator <= 0) {
+            throw invalidTelegramMultipartBody("Multipart part contains a malformed header.");
+        }
+        if (line.slice(0, separator).trim().toLowerCase() === "content-disposition") {
+            contentDisposition = line.slice(separator + 1).trim();
+        }
+    }
+    if (!contentDisposition) {
+        throw invalidTelegramMultipartBody("Multipart part is missing a form-data disposition.");
+    }
+    const parsed = parseTelegramMimeParameters(contentDisposition, { decodeQuotedPairs: true });
+    if (parsed.type !== "form-data") {
+        throw invalidTelegramMultipartBody("Multipart part is missing a form-data disposition.");
+    }
+    const rawName = parsed.parameters.get("name");
+    if (rawName === undefined) {
+        throw invalidTelegramMultipartBody("Multipart part is missing a field name.");
+    }
+    const rawFileName = parsed.parameters.get("filename");
+    const rawExtendedFileName = parsed.parameters.get("filename*");
+    return {
+        ...(rawExtendedFileName !== undefined
+            ? { fileName: decodeTelegramMultipartExtendedParameter(rawExtendedFileName) }
+            : rawFileName !== undefined
+                ? { fileName: decodeTelegramMultipartParameter(rawFileName) }
+                : {}),
+        name: decodeTelegramMultipartParameter(rawName),
+    };
+}
+class TelegramMultipartReader {
+    request;
+    maxBytes;
+    #iterator;
+    #buffer = Buffer.alloc(0);
+    #ended = false;
+    #totalBytes = 0;
+    constructor(request, maxBytes) {
+        this.request = request;
+        this.maxBytes = maxBytes;
+        this.#iterator = request[Symbol.asyncIterator]();
+    }
+    async readUntil(delimiter, maxBytes) {
+        const chunks = [];
+        let length = 0;
+        while (true) {
+            const delimiterIndex = this.#buffer.indexOf(delimiter);
+            if (delimiterIndex >= 0) {
+                length += delimiterIndex;
+                if (length > maxBytes) {
+                    throw new RequestBodyTooLargeError(maxBytes);
+                }
+                chunks.push(this.#buffer.subarray(0, delimiterIndex));
+                this.#consume(delimiterIndex + delimiter.length);
+                return Buffer.concat(chunks, length);
+            }
+            const emitLength = Math.max(0, this.#buffer.length - delimiter.length + 1);
+            if (emitLength > 0) {
+                length += emitLength;
+                if (length > maxBytes) {
+                    throw new RequestBodyTooLargeError(maxBytes);
+                }
+                chunks.push(this.#buffer.subarray(0, emitLength));
+                this.#consume(emitLength);
+            }
+            if (!(await this.#readMore())) {
+                throw invalidTelegramMultipartBody("Multipart delimiter is incomplete.");
+            }
+        }
+    }
+    async readInitialBoundary(boundary, maxPreambleBytes) {
+        const lineBoundary = Buffer.concat([Buffer.from("\r\n"), boundary]);
+        let preambleBytes = 0;
+        let checkBodyStart = true;
+        while (true) {
+            if (checkBodyStart) {
+                await this.#ensure(boundary.length + 2);
+                checkBodyStart = false;
+                if (this.#buffer.subarray(0, boundary.length).equals(boundary)) {
+                    const suffix = await this.#readBoundarySuffix(boundary.length);
+                    if (suffix) {
+                        this.#consume(suffix.consumedBytes);
+                        return suffix.kind;
+                    }
+                }
+            }
+            const boundaryIndex = this.#buffer.indexOf(lineBoundary);
+            if (boundaryIndex >= 0) {
+                const suffixOffset = boundaryIndex + lineBoundary.length;
+                if (this.#buffer.length < suffixOffset + 2) {
+                    if (boundaryIndex > 0) {
+                        preambleBytes += boundaryIndex;
+                        if (preambleBytes > maxPreambleBytes) {
+                            throw new RequestBodyTooLargeError(maxPreambleBytes);
+                        }
+                        this.#consume(boundaryIndex);
+                    }
+                    if (!(await this.#readMore())) {
+                        throw invalidTelegramMultipartBody("Multipart boundary is incomplete.");
+                    }
+                    continue;
+                }
+                const suffix = await this.#readBoundarySuffix(suffixOffset);
+                if (suffix) {
+                    preambleBytes += boundaryIndex;
+                    if (preambleBytes > maxPreambleBytes) {
+                        throw new RequestBodyTooLargeError(maxPreambleBytes);
+                    }
+                    this.#consume(suffix.consumedBytes);
+                    return suffix.kind;
+                }
+                const emitLength = suffixOffset;
+                preambleBytes += emitLength;
+                if (preambleBytes > maxPreambleBytes) {
+                    throw new RequestBodyTooLargeError(maxPreambleBytes);
+                }
+                this.#consume(emitLength);
+                continue;
+            }
+            const emitLength = Math.max(0, this.#buffer.length - lineBoundary.length + 1);
+            if (emitLength > 0) {
+                preambleBytes += emitLength;
+                if (preambleBytes > maxPreambleBytes) {
+                    throw new RequestBodyTooLargeError(maxPreambleBytes);
+                }
+                this.#consume(emitLength);
+            }
+            if (!(await this.#readMore())) {
+                throw invalidTelegramMultipartBody("Multipart body is missing its initial boundary.");
+            }
+        }
+    }
+    async readPartBody(boundaryMarker, onChunk) {
+        while (true) {
+            const boundaryIndex = this.#buffer.indexOf(boundaryMarker);
+            if (boundaryIndex >= 0) {
+                const suffixOffset = boundaryIndex + boundaryMarker.length;
+                if (this.#buffer.length < suffixOffset + 2) {
+                    if (boundaryIndex > 0) {
+                        onChunk(this.#buffer.subarray(0, boundaryIndex));
+                        this.#consume(boundaryIndex);
+                    }
+                    if (!(await this.#readMore())) {
+                        throw invalidTelegramMultipartBody("Multipart boundary is incomplete.");
+                    }
+                    continue;
+                }
+                const suffix = await this.#readBoundarySuffix(suffixOffset);
+                if (suffix) {
+                    if (boundaryIndex > 0) {
+                        onChunk(this.#buffer.subarray(0, boundaryIndex));
+                    }
+                    this.#consume(suffix.consumedBytes);
+                    return suffix.kind;
+                }
+                const emitLength = suffixOffset;
+                onChunk(this.#buffer.subarray(0, emitLength));
+                this.#consume(emitLength);
+                continue;
+            }
+            const emitLength = Math.max(0, this.#buffer.length - boundaryMarker.length + 1);
+            if (emitLength > 0) {
+                onChunk(this.#buffer.subarray(0, emitLength));
+                this.#consume(emitLength);
+            }
+            if (!(await this.#readMore())) {
+                throw invalidTelegramMultipartBody("Multipart body is missing its closing boundary.");
+            }
+        }
+    }
+    async consumeRemainder() {
+        while (await this.#readMore()) {
+            this.#buffer = Buffer.alloc(0);
+        }
+    }
+    #consume(length) {
+        this.#buffer = this.#buffer.subarray(length);
+    }
+    async #ensure(length) {
+        while (this.#buffer.length < length) {
+            if (!(await this.#readMore())) {
+                throw invalidTelegramMultipartBody("Multipart body ended unexpectedly.");
+            }
+        }
+    }
+    async #readBoundarySuffix(suffixOffset) {
+        await this.#ensure(suffixOffset + 2);
+        const suffix = this.#buffer.subarray(suffixOffset, suffixOffset + 2);
+        const final = suffix.equals(Buffer.from("--"));
+        let lineEnd = suffixOffset + (final ? 2 : 0);
+        while (true) {
+            while (lineEnd < this.#buffer.length &&
+                (this.#buffer[lineEnd] === 0x20 || this.#buffer[lineEnd] === 0x09)) {
+                lineEnd += 1;
+                if (lineEnd - suffixOffset > TELEGRAM_MAX_MULTIPART_HEADER_BYTES) {
+                    return undefined;
+                }
+            }
+            if (lineEnd >= this.#buffer.length) {
+                if (await this.#readMore()) {
+                    continue;
+                }
+                return final ? { consumedBytes: lineEnd, kind: "final" } : undefined;
+            }
+            if (this.#buffer[lineEnd] !== 0x0d) {
+                return undefined;
+            }
+            if (lineEnd + 1 >= this.#buffer.length) {
+                if (await this.#readMore()) {
+                    continue;
+                }
+                return undefined;
+            }
+            return this.#buffer[lineEnd + 1] === 0x0a
+                ? { consumedBytes: lineEnd + 2, kind: final ? "final" : "next" }
+                : undefined;
+        }
+    }
+    async #readMore() {
+        if (this.#ended) {
+            return false;
+        }
+        const next = await this.#iterator.next();
+        if (next.done) {
+            this.#ended = true;
+            return false;
+        }
+        const chunk = Buffer.isBuffer(next.value) ? next.value : Buffer.from(next.value);
+        this.#totalBytes += chunk.length;
+        if (this.#totalBytes > this.maxBytes) {
+            throw new RequestBodyTooLargeError(this.maxBytes);
+        }
+        this.#buffer =
+            this.#buffer.length === 0
+                ? chunk
+                : Buffer.concat([this.#buffer, chunk], this.#buffer.length + chunk.length);
+        return true;
+    }
+}
+function enforceTelegramMultipartContentLength(request) {
+    const contentLengthHeader = request.headers["content-length"];
+    const contentLength = Array.isArray(contentLengthHeader)
+        ? contentLengthHeader[0]
+        : contentLengthHeader;
+    if (contentLength && /^\d+$/u.test(contentLength)) {
+        const bytes = Number(contentLength);
+        if (!Number.isSafeInteger(bytes) || bytes > TELEGRAM_MAX_REQUEST_BODY_BYTES) {
+            drainRequestBody(request);
+            throw new RequestBodyTooLargeError(TELEGRAM_MAX_REQUEST_BODY_BYTES);
+        }
+    }
+}
+async function parseMultipartFormDataRequest(request, contentType) {
+    enforceTelegramMultipartContentLength(request);
+    try {
+        const boundary = parseTelegramMultipartBoundary(contentType);
+        const bodyBoundary = Buffer.concat([Buffer.from("\r\n"), boundary]);
+        const reader = new TelegramMultipartReader(request, TELEGRAM_MAX_REQUEST_BODY_BYTES);
+        const fields = Object.create(null);
+        let retainedTextBytes = 0;
+        let partCount = 0;
+        let boundaryKind = await reader.readInitialBoundary(boundary, TELEGRAM_MAX_MULTIPART_HEADER_BYTES);
+        while (boundaryKind !== "final") {
+            partCount += 1;
+            if (partCount > TELEGRAM_MAX_MULTIPART_PARTS) {
+                throw new RequestBodyTooLargeError(TELEGRAM_MAX_MULTIPART_PARTS);
+            }
+            const disposition = parseTelegramMultipartDisposition(await reader.readUntil(Buffer.from("\r\n\r\n"), TELEGRAM_MAX_MULTIPART_HEADER_BYTES));
+            const digest = disposition.fileName === undefined ? undefined : createHash("sha256");
+            const textChunks = [];
+            let textLength = 0;
+            boundaryKind = await reader.readPartBody(bodyBoundary, (chunk) => {
+                if (digest) {
+                    digest.update(chunk);
+                    return;
+                }
+                retainedTextBytes += chunk.length;
+                textLength += chunk.length;
+                if (retainedTextBytes > TELEGRAM_MAX_MULTIPART_TEXT_BYTES) {
+                    throw new RequestBodyTooLargeError(TELEGRAM_MAX_MULTIPART_TEXT_BYTES);
+                }
+                textChunks.push(Buffer.from(chunk));
+            });
+            fields[disposition.name] =
+                digest && disposition.fileName !== undefined
+                    ? {
+                        [TELEGRAM_MULTIPART_FILE]: true,
+                        contentDigest: digest.digest("base64url"),
+                        fileName: disposition.fileName,
+                    }
+                    : Buffer.concat(textChunks, textLength).toString("utf8");
+        }
+        await reader.consumeRemainder();
+        return fields;
     }
-    const fields = {};
-    for (const [name, value] of form) {
-        fields[name] = typeof value === "string" ? value : value.name;
+    catch (error) {
+        drainRequestBody(request);
+        throw error;
     }
-    return fields;
 }
 function requireTelegramBotPath(pathname) {
     const match = /^\/bot([^/]+)\/([A-Za-z][A-Za-z0-9_]*)$/u.exec(pathname);
@@ -135,18 +574,48 @@ function telegramChatId(value) {
         return undefined;
     }
     if (/^-?\d+$/u.test(stringValue)) {
-        const integerValue = toIntegerValue(stringValue);
-        return integerValue === 0 ? undefined : integerValue;
+        return telegramNumericChatId(stringValue);
+    }
+    return telegramUsernameChatId(stringValue);
+}
+function telegramNumericChatId(value) {
+    const stringValue = toStringValue(value);
+    if (!stringValue || !/^-?\d+$/u.test(stringValue)) {
+        return undefined;
     }
-    return TELEGRAM_CHAT_USERNAME_PATTERN.test(stringValue) ? stringValue : undefined;
+    const integerValue = BigInt(stringValue);
+    if (integerValue === 0n ||
+        integerValue < -TELEGRAM_NATIVE_CHAT_ID_MAX ||
+        integerValue > TELEGRAM_NATIVE_CHAT_ID_MAX) {
+        return undefined;
+    }
+    return Number(integerValue);
+}
+function telegramStoredChatId(value) {
+    const nativeChatId = telegramNumericChatId(value);
+    if (nativeChatId !== undefined) {
+        return nativeChatId;
+    }
+    const chatId = toIntegerValue(value);
+    return chatId !== undefined && isTelegramUsernameChatId(chatId) ? chatId : undefined;
 }
 async function appendEvent(state, event) {
     await recordServerEvent({ event, onEvent: state.onEvent, recorderPath: state.recorderPath });
 }
+function isTelegramMultipartFile(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        TELEGRAM_MULTIPART_FILE in value &&
+        value[TELEGRAM_MULTIPART_FILE] === true);
+}
 function redactTelegramSecrets(body) {
     return Object.fromEntries(Object.entries(body).map(([key, value]) => [
         key,
-        key === "secret_token" ? "<redacted>" : value,
+        key === "secret_token"
+            ? "<redacted>"
+            : isTelegramMultipartFile(value)
+                ? value.fileName
+                : value,
     ]));
 }
 function createBotUser(state) {
@@ -154,73 +623,242 @@ function createBotUser(state) {
         can_join_groups: true,
         can_read_all_group_messages: true,
         first_name: "Crabline",
-        has_topics_enabled: true,
+        ...(state.botHasTopicsEnabled ? { has_topics_enabled: true } : {}),
         id: state.botId,
         is_bot: true,
         supports_inline_queries: false,
         username: state.botUsername,
     };
 }
+function inferTelegramChatType(chatId) {
+    return chatId >= 0
+        ? "private"
+        : String(chatId).startsWith("-100") || isTelegramUsernameChatId(chatId)
+            ? "supergroup"
+            : "group";
+}
 function createChat(chatId) {
-    const type = typeof chatId === "string"
-        ? "supergroup"
-        : chatId >= 0
-            ? "private"
-            : String(chatId).startsWith("-100")
-                ? "supergroup"
-                : "group";
     return {
         id: chatId,
+        type: inferTelegramChatType(chatId),
+    };
+}
+function telegramDestinationUsername(value) {
+    const username = toStringValue(value);
+    return username ? canonicalizeTelegramUsername(username) : undefined;
+}
+function telegramStoredUsername(value) {
+    const username = toStringValue(value)?.trim();
+    if (!username) {
+        return undefined;
+    }
+    return canonicalizeTelegramUsername(username.startsWith("@") ? username : `@${username}`)?.slice(1);
+}
+function telegramChatType(value) {
+    return value === "channel" || value === "group" || value === "private" || value === "supergroup"
+        ? value
+        : undefined;
+}
+function registerTelegramChat(state, chat) {
+    const previous = state.chatsById.get(chat.id);
+    const previousUsername = telegramStoredUsername(previous?.username);
+    if (previousUsername && state.chatsByUsername.get(previousUsername)?.id === chat.id) {
+        state.chatsByUsername.delete(previousUsername);
+    }
+    const username = telegramStoredUsername(chat.username);
+    const stored = {
+        id: chat.id,
+        ...(chat.type === "supergroup" && chat.is_forum === true ? { is_forum: true } : {}),
+        ...(chat.title ? { title: chat.title } : {}),
+        type: chat.type,
+        ...(username ? { username } : {}),
+    };
+    state.chatsById.set(chat.id, stored);
+    if (username) {
+        state.chatsByUsername.set(username, stored);
+    }
+}
+function resolveTelegramChat(state, value) {
+    const stringValue = toStringValue(value);
+    if (!stringValue) {
+        return undefined;
+    }
+    if (/^-?\d+$/u.test(stringValue)) {
+        const chatId = telegramChatId(stringValue);
+        if (chatId === undefined) {
+            return undefined;
+        }
+        return state.chatsById.get(chatId) ?? createChat(chatId);
+    }
+    const username = telegramDestinationUsername(stringValue);
+    if (!username) {
+        return undefined;
+    }
+    const storedUsername = username.slice(1);
+    const registered = state.chatsByUsername.get(storedUsername);
+    if (registered) {
+        return registered;
+    }
+    const chatId = telegramUsernameChatId(username);
+    return chatId === undefined
+        ? undefined
+        : {
+            id: chatId,
+            type: inferTelegramChatType(chatId),
+            username: storedUsername,
+        };
+}
+function telegramChatFromRecord(value) {
+    if (!isJsonObject(value)) {
+        return undefined;
+    }
+    const id = telegramStoredChatId(value.id);
+    const type = telegramChatType(value.type);
+    if (id === undefined || !type) {
+        return undefined;
+    }
+    const username = telegramStoredUsername(value.username);
+    const title = toStringValue(value.title);
+    const isForum = value.is_forum === true;
+    if (isForum && type !== "supergroup") {
+        return undefined;
+    }
+    return {
+        id,
+        ...(isForum ? { is_forum: true } : {}),
+        ...(title ? { title } : {}),
         type,
+        ...(username ? { username } : {}),
     };
 }
-function createOutboundMessage(state, body) {
-    const chatId = telegramChatId(body.chat_id);
-    const text = toStringValue(body.text);
-    if (chatId === undefined || !text) {
+function registerTelegramMessageChat(state, message) {
+    const chat = telegramChatFromRecord(message.chat);
+    if (!chat) {
+        return;
+    }
+    registerTelegramChat(state, chat);
+}
+function registerTelegramUpdateChats(state, body) {
+    for (const field of TELEGRAM_MESSAGE_UPDATE_FIELDS) {
+        const message = body[field];
+        if (!isJsonObject(message)) {
+            continue;
+        }
+        registerTelegramMessageChat(state, message);
+    }
+    const callbackQuery = isJsonObject(body.callback_query) ? body.callback_query : undefined;
+    const callbackMessage = callbackQuery && isJsonObject(callbackQuery.message) ? callbackQuery.message : undefined;
+    if (callbackMessage) {
+        registerTelegramMessageChat(state, callbackMessage);
+    }
+    for (const field of TELEGRAM_CHAT_UPDATE_FIELDS) {
+        const update = body[field];
+        if (!isJsonObject(update)) {
+            continue;
+        }
+        const chat = telegramChatFromRecord(update.chat);
+        if (chat) {
+            registerTelegramChat(state, chat);
+        }
+    }
+}
+function telegramChatKey(chatId) {
+    return `number:${chatId}`;
+}
+function nextTelegramMessageId(state, chatId) {
+    return state.nextMessageIds.get(telegramChatKey(chatId)) ?? 1;
+}
+function takeNextTelegramMessageId(state, chatId) {
+    const messageId = nextTelegramMessageId(state, chatId);
+    if (messageId >= Number.MAX_SAFE_INTEGER) {
+        return undefined;
+    }
+    state.nextMessageIds.set(telegramChatKey(chatId), messageId + 1);
+    return messageId;
+}
+function createOutboundMessage(state, body, text) {
+    const chat = resolveTelegramChat(state, body.chat_id);
+    if (!chat) {
         return undefined;
     }
-    const parsedThreadId = toIntegerValue(body.message_thread_id);
+    const parsedThreadId = telegramMessageThreadId(body.message_thread_id);
     if (body.message_thread_id !== undefined && parsedThreadId === undefined) {
         return undefined;
     }
-    const threadId = parsedThreadId !== undefined && parsedThreadId > 0 ? parsedThreadId : undefined;
+    if (parsedThreadId !== undefined && !canTargetTelegramTopic(state, chat)) {
+        return undefined;
+    }
+    const messageId = takeNextTelegramMessageId(state, chat.id);
+    if (messageId === undefined) {
+        return undefined;
+    }
     return {
-        chat: createChat(chatId),
+        chat,
         date: Math.floor(Date.now() / 1000),
         from: createBotUser(state),
-        message_id: state.nextMessageId++,
-        ...(threadId !== undefined ? { message_thread_id: threadId } : {}),
+        message_id: messageId,
+        ...(parsedThreadId !== undefined ? { message_thread_id: parsedThreadId } : {}),
         text,
     };
 }
-function createOutboundMediaMessage(state, body, mediaKind) {
-    const chatId = telegramChatId(body.chat_id);
-    const fileName = toStringValue(body[mediaKind]);
-    if (chatId === undefined || !fileName) {
+function createOutboundMediaMessage(state, body, mediaKind, caption) {
+    const chat = resolveTelegramChat(state, body.chat_id);
+    const mediaInput = body[mediaKind];
+    const multipartFile = isTelegramMultipartFile(mediaInput) ? mediaInput : undefined;
+    const fileName = multipartFile?.fileName ?? toStringValue(mediaInput);
+    if (!chat || !fileName) {
         return undefined;
     }
-    const parsedThreadId = toIntegerValue(body.message_thread_id);
+    const parsedThreadId = telegramMessageThreadId(body.message_thread_id);
     if (body.message_thread_id !== undefined && parsedThreadId === undefined) {
         return undefined;
     }
-    const threadId = parsedThreadId !== undefined && parsedThreadId > 0 ? parsedThreadId : undefined;
-    const caption = toStringValue(body.caption);
+    if (parsedThreadId !== undefined && !canTargetTelegramTopic(state, chat)) {
+        return undefined;
+    }
+    const messageId = takeNextTelegramMessageId(state, chat.id);
+    if (messageId === undefined) {
+        return undefined;
+    }
     const duration = Math.max(0, toIntegerValue(body.duration) ?? 0);
     const height = Math.max(1, toIntegerValue(body.height) ?? 1);
     const width = Math.max(1, toIntegerValue(body.width) ?? 1);
+    const chatIdentity = Buffer.from(telegramChatKey(chat.id)).toString("base64url");
+    let fileIdentity;
+    if (multipartFile) {
+        fileIdentity = multipartFile.contentDigest.slice(0, 32);
+    }
+    else {
+        fileIdentity =
+            new RegExp(`^crabline-${mediaKind}-([A-Za-z0-9_-]{32})-`, "u").exec(fileName)?.[1] ??
+                createHash("sha256")
+                    .update(mediaKind)
+                    .update("\0")
+                    .update(fileName)
+                    .digest("base64url")
+                    .slice(0, 32);
+    }
+    const fileId = `crabline-${mediaKind}-${fileIdentity}-${chatIdentity}-${messageId}`;
+    const fileUniqueId = `crabline-${mediaKind}-unique-${fileIdentity}`;
     const media = {
-        file_id: `crabline-${mediaKind}-${state.nextMessageId}`,
+        file_id: fileId,
         file_name: fileName,
-        file_unique_id: `crabline-${mediaKind}-unique-${state.nextMessageId}`,
+        file_unique_id: fileUniqueId,
     };
     return {
-        chat: createChat(chatId),
+        chat,
         date: Math.floor(Date.now() / 1000),
         from: createBotUser(state),
         ...(caption ? { caption } : {}),
         [mediaKind]: mediaKind === "photo"
-            ? [{ ...media, height: 1, width: 1 }]
+            ? [
+                {
+                    file_id: media.file_id,
+                    file_unique_id: media.file_unique_id,
+                    height: 1,
+                    width: 1,
+                },
+            ]
             : {
                 ...media,
                 ...(mediaKind === "audio"
@@ -230,35 +868,39 @@ function createOutboundMediaMessage(state, body, mediaKind) {
                         : {}),
                 mime_type: "application/octet-stream",
             },
-        message_id: state.nextMessageId++,
-        ...(threadId !== undefined ? { message_thread_id: threadId } : {}),
+        message_id: messageId,
+        ...(parsedThreadId !== undefined ? { message_thread_id: parsedThreadId } : {}),
     };
 }
-function createEditedMessage(state, body) {
-    const chatId = telegramChatId(body.chat_id);
-    const text = toStringValue(body.text);
+function createEditedMessage(state, body, text) {
+    const chat = resolveTelegramChat(state, body.chat_id);
     const messageId = toIntegerValue(body.message_id);
-    if (chatId === undefined || !text || messageId === undefined) {
+    if (!chat || messageId === undefined || messageId < 1) {
         return undefined;
     }
-    const parsedThreadId = toIntegerValue(body.message_thread_id);
+    const parsedThreadId = telegramMessageThreadId(body.message_thread_id);
     if (body.message_thread_id !== undefined && parsedThreadId === undefined) {
         return undefined;
     }
-    const threadId = parsedThreadId !== undefined && parsedThreadId > 0 ? parsedThreadId : undefined;
+    if (parsedThreadId !== undefined && !canTargetTelegramTopic(state, chat)) {
+        return undefined;
+    }
     return {
-        chat: createChat(chatId),
+        chat,
         date: Math.floor(Date.now() / 1000),
         from: createBotUser(state),
         message_id: messageId,
-        ...(threadId !== undefined ? { message_thread_id: threadId } : {}),
+        ...(parsedThreadId !== undefined ? { message_thread_id: parsedThreadId } : {}),
         text,
     };
 }
 function createInboundUpdate(state, body) {
-    const chatId = telegramChatId(body.chatId ?? body.chat_id);
-    const text = toStringValue(body.text);
-    if (chatId === undefined || !text) {
+    const chat = resolveTelegramChat(state, body.chatId ?? body.chat_id);
+    const text = body.text;
+    if (!chat ||
+        typeof text !== "string" ||
+        text.length < 1 ||
+        text.length > TELEGRAM_MAX_TEXT_LENGTH) {
         return undefined;
     }
     const fromIdValue = body.fromId ?? body.from_id;
@@ -266,24 +908,43 @@ function createInboundUpdate(state, body) {
     const messageIdValue = body.messageId ?? body.message_id;
     const updateIdValue = body.updateId ?? body.update_id;
     const fromId = toIntegerValue(fromIdValue);
-    const parsedThreadId = toIntegerValue(threadIdValue);
-    const threadId = parsedThreadId !== undefined && parsedThreadId > 0 ? parsedThreadId : undefined;
-    const fromUsername = toStringValue(body.fromUsername ?? body.from_username);
+    const threadId = telegramMessageThreadId(threadIdValue);
+    const fromUsernameValue = body.fromUsername ?? body.from_username;
+    const fromUsername = telegramStoredUsername(fromUsernameValue);
     const messageId = toIntegerValue(messageIdValue);
     const updateId = toIntegerValue(updateIdValue);
-    if ((fromIdValue !== undefined && fromId === undefined) ||
-        (threadIdValue !== undefined && parsedThreadId === undefined) ||
-        (messageIdValue !== undefined && messageId === undefined) ||
-        (updateIdValue !== undefined && updateId === undefined)) {
+    const explicitChatType = telegramChatType(body.chatType ?? body.chat_type);
+    const isForumValue = body.isForum ?? body.is_forum;
+    if (((body.chatType !== undefined || body.chat_type !== undefined) && !explicitChatType) ||
+        (isForumValue !== undefined && typeof isForumValue !== "boolean") ||
+        (fromIdValue !== undefined && (fromId === undefined || fromId < 1)) ||
+        (fromUsernameValue !== undefined && !fromUsername) ||
+        (threadIdValue !== undefined && threadId === undefined) ||
+        (messageIdValue !== undefined && (messageId === undefined || messageId < 1)) ||
+        (updateIdValue !== undefined && (updateId === undefined || updateId < 1))) {
         return undefined;
     }
     const entities = parseTelegramEntities(body.entities, text);
     if (body.entities !== undefined && !entities) {
         return undefined;
     }
+    const inboundChat = {
+        ...chat,
+        ...(explicitChatType ? { type: explicitChatType } : {}),
+        ...(isForumValue === true ? { is_forum: true } : {}),
+    };
+    if (isForumValue === false) {
+        delete inboundChat.is_forum;
+    }
+    if (inboundChat.is_forum === true && inboundChat.type !== "supergroup") {
+        return undefined;
+    }
+    if (threadId !== undefined && !canTargetTelegramTopic(state, inboundChat)) {
+        return undefined;
+    }
     return {
         message: {
-            chat: createChat(chatId),
+            chat: inboundChat,
             date: Math.floor(Date.now() / 1000),
             from: {
                 first_name: toStringValue(body.fromName ?? body.from_name) ?? "QA User",
@@ -291,7 +952,7 @@ function createInboundUpdate(state, body) {
                 is_bot: false,
                 ...(fromUsername ? { username: fromUsername } : {}),
             },
-            message_id: messageId ?? state.nextMessageId,
+            message_id: messageId ?? nextTelegramMessageId(state, chat.id),
             ...(entities && entities.length > 0 ? { entities } : {}),
             ...(threadId !== undefined ? { message_thread_id: threadId } : {}),
             text,
@@ -313,22 +974,297 @@ function parseTelegramEntities(value, text) {
         }
         const length = toIntegerValue(entry.length);
         const offset = toIntegerValue(entry.offset);
-        const type = toStringValue(entry.type);
+        const type = typeof entry.type === "string" && entry.type.length > 0 ? entry.type : undefined;
+        const customEmojiId = entry.custom_emoji_id;
+        const language = entry.language;
+        const url = entry.url;
+        const user = entry.user;
         if (length === undefined ||
             length < 1 ||
             offset === undefined ||
             offset < 0 ||
             offset + length > text.length ||
-            !type) {
+            !isTelegramUtf16Boundary(text, offset) ||
+            !isTelegramUtf16Boundary(text, offset + length) ||
+            !type ||
+            (customEmojiId !== undefined &&
+                (typeof customEmojiId !== "string" || customEmojiId.length === 0)) ||
+            (language !== undefined && (typeof language !== "string" || language.length === 0)) ||
+            (url !== undefined && (typeof url !== "string" || url.length === 0)) ||
+            (user !== undefined && !isJsonObject(user))) {
             return undefined;
         }
-        entities.push({ length, offset, type });
+        entities.push({
+            ...(customEmojiId !== undefined ? { custom_emoji_id: customEmojiId } : {}),
+            ...(language !== undefined ? { language } : {}),
+            length,
+            offset,
+            type,
+            ...(url !== undefined ? { url } : {}),
+            ...(user !== undefined ? { user } : {}),
+        });
     }
     return entities;
 }
+function isTelegramUtf16Boundary(text, index) {
+    if (index <= 0 || index >= text.length) {
+        return true;
+    }
+    const previous = text.charCodeAt(index - 1);
+    const next = text.charCodeAt(index);
+    return !(previous >= 0xd800 && previous <= 0xdbff && next >= 0xdc00 && next <= 0xdfff);
+}
 function hasTelegramMedia(value) {
     return TELEGRAM_MEDIA_FIELDS.some((field) => value[field] !== undefined);
 }
+function telegramMessageThreadId(value) {
+    const threadId = toIntegerValue(value);
+    return threadId !== undefined && threadId > 0 ? threadId : undefined;
+}
+function canTargetTelegramTopic(state, chat) {
+    if (chat.type === "supergroup") {
+        return chat.is_forum === true;
+    }
+    if (chat.type === "private") {
+        return state.botHasTopicsEnabled;
+    }
+    return false;
+}
+function telegramMessageTargetsValidTopic(state, message) {
+    if (message.message_thread_id === undefined) {
+        return true;
+    }
+    const chat = telegramChatFromRecord(message.chat);
+    if (!chat) {
+        return false;
+    }
+    return canTargetTelegramTopic(state, chat);
+}
+function hasValidTelegramTopicDestinations(state, body) {
+    const topLevelThreadId = body.messageThreadId ?? body.message_thread_id;
+    if (topLevelThreadId !== undefined) {
+        const chat = resolveTelegramChat(state, body.chatId ?? body.chat_id);
+        const explicitType = telegramChatType(body.chatType ?? body.chat_type);
+        if (!chat || ((body.chatType !== undefined || body.chat_type !== undefined) && !explicitType)) {
+            return false;
+        }
+        const topicChat = {
+            ...chat,
+            ...(explicitType ? { type: explicitType } : {}),
+            ...((body.isForum ?? body.is_forum) === true ? { is_forum: true } : {}),
+        };
+        if ((body.isForum ?? body.is_forum) === false) {
+            delete topicChat.is_forum;
+        }
+        if ((body.isForum !== undefined || body.is_forum !== undefined) &&
+            typeof (body.isForum ?? body.is_forum) !== "boolean") {
+            return false;
+        }
+        if (!canTargetTelegramTopic(state, topicChat)) {
+            return false;
+        }
+    }
+    for (const field of TELEGRAM_MESSAGE_UPDATE_FIELDS) {
+        const message = body[field];
+        if (isJsonObject(message) && !telegramMessageTargetsValidTopic(state, message)) {
+            return false;
+        }
+    }
+    const callbackQuery = isJsonObject(body.callback_query) ? body.callback_query : undefined;
+    const callbackMessage = callbackQuery && isJsonObject(callbackQuery.message) ? callbackQuery.message : undefined;
+    return !callbackMessage || telegramMessageTargetsValidTopic(state, callbackMessage);
+}
+function hasValidTelegramMessageThreadIds(body) {
+    const values = [
+        body.messageThreadId,
+        body.message_thread_id,
+        ...TELEGRAM_MESSAGE_UPDATE_FIELDS.flatMap((field) => {
+            const message = body[field];
+            return isJsonObject(message) ? [message.message_thread_id] : [];
+        }),
+    ];
+    const callbackQuery = isJsonObject(body.callback_query) ? body.callback_query : undefined;
+    const callbackMessage = callbackQuery && isJsonObject(callbackQuery.message) ? callbackQuery.message : undefined;
+    if (callbackMessage) {
+        values.push(callbackMessage.message_thread_id);
+    }
+    return values.every((value) => value === undefined || telegramMessageThreadId(value) !== undefined);
+}
+function explicitTelegramId(body, names, additionalValues = [], options = {}) {
+    const values = [
+        ...names.flatMap((name) => (body[name] === undefined ? [] : [body[name]])),
+        ...additionalValues.filter((value) => value !== undefined),
+    ];
+    if (values.length === 0) {
+        return { present: false };
+    }
+    const parsed = values.map(toIntegerValue);
+    const minimum = options.allowZero ? 0 : 1;
+    if (parsed.some((value) => value === undefined || value < minimum || value >= Number.MAX_SAFE_INTEGER) ||
+        new Set(parsed).size !== 1) {
+        return undefined;
+    }
+    return { present: true, value: parsed[0] };
+}
+function explicitTelegramMessageIdValues(body) {
+    return TELEGRAM_NEW_MESSAGE_UPDATE_FIELDS.flatMap((field) => {
+        const message = body[field];
+        return isJsonObject(message) ? [message.message_id] : [];
+    });
+}
+function referencedTelegramMessageIdValues(body) {
+    const values = TELEGRAM_MESSAGE_REFERENCE_FIELDS.flatMap((field) => {
+        const message = body[field];
+        return isJsonObject(message) ? [message.message_id] : [];
+    });
+    const callbackQuery = isJsonObject(body.callback_query) ? body.callback_query : undefined;
+    const callbackMessage = callbackQuery && isJsonObject(callbackQuery.message) ? callbackQuery.message : undefined;
+    return callbackMessage ? [...values, callbackMessage.message_id] : values;
+}
+function explicitTelegramMessageChatId(body) {
+    const chatIds = [];
+    if (body.messageId !== undefined || body.message_id !== undefined) {
+        const chatId = telegramChatId(body.chatId ?? body.chat_id);
+        if (chatId === undefined) {
+            return false;
+        }
+        chatIds.push(chatId);
+    }
+    for (const field of TELEGRAM_MESSAGE_UPDATE_FIELDS) {
+        const message = body[field];
+        if (!isJsonObject(message) || message.message_id === undefined) {
+            continue;
+        }
+        const chat = isJsonObject(message.chat) ? message.chat : undefined;
+        const chatId = telegramStoredChatId(chat?.id);
+        if (chatId === undefined) {
+            return false;
+        }
+        chatIds.push(chatId);
+    }
+    const callbackQuery = isJsonObject(body.callback_query) ? body.callback_query : undefined;
+    const callbackMessage = callbackQuery && isJsonObject(callbackQuery.message) ? callbackQuery.message : undefined;
+    if (callbackMessage?.message_id !== undefined) {
+        const chat = isJsonObject(callbackMessage.chat) ? callbackMessage.chat : undefined;
+        const chatId = telegramStoredChatId(chat?.id);
+        if (chatId === undefined) {
+            return false;
+        }
+        chatIds.push(chatId);
+    }
+    if (chatIds.length === 0) {
+        return undefined;
+    }
+    const firstChatId = chatIds[0];
+    return chatIds.every((chatId) => telegramChatKey(chatId) === telegramChatKey(firstChatId))
+        ? firstChatId
+        : false;
+}
+function readTelegramTextField(value, field, options) {
+    if (value === undefined) {
+        return options.required ? telegramError(`Bad Request: ${field} is required`) : undefined;
+    }
+    if (typeof value !== "string") {
+        return telegramError(`Bad Request: ${field} must be a string`);
+    }
+    const parsedLength = telegramTextLength(value, options.parseMode);
+    if (options.required && parsedLength === 0) {
+        return telegramError(`Bad Request: ${field} must not be empty`);
+    }
+    const maxLength = field === "text" ? TELEGRAM_MAX_TEXT_LENGTH : TELEGRAM_MAX_CAPTION_LENGTH;
+    if (parsedLength > maxLength) {
+        return telegramError(`Bad Request: ${field} is too long`);
+    }
+    return value;
+}
+function telegramTextLength(value, parseMode) {
+    const normalizedParseMode = typeof parseMode === "string" ? parseMode.toLowerCase() : undefined;
+    if (normalizedParseMode === "html") {
+        return telegramHtmlText(value).length;
+    }
+    if (normalizedParseMode === "markdown" || normalizedParseMode === "markdownv2") {
+        return telegramMarkdownText(value, normalizedParseMode === "markdownv2").length;
+    }
+    return value.length;
+}
+function telegramHtmlText(value) {
+    return value
+        .replace(TELEGRAM_HTML_TAG_PATTERN, "")
+        .replace(TELEGRAM_HTML_ENTITY_PATTERN, (entity) => {
+        const normalized = entity.toLowerCase();
+        if (normalized === "&amp;") {
+            return "&";
+        }
+        if (normalized === "&gt;") {
+            return ">";
+        }
+        if (normalized === "&lt;") {
+            return "<";
+        }
+        if (normalized === "&quot;") {
+            return '"';
+        }
+        const radix = normalized.startsWith("&#x") ? 16 : 10;
+        const digits = normalized.slice(radix === 16 ? 3 : 2, -1);
+        const codePoint = Number.parseInt(digits, radix);
+        return Number.isSafeInteger(codePoint) && codePoint <= 0x10ffff
+            ? String.fromCodePoint(codePoint)
+            : entity;
+    });
+}
+function protectTelegramMarkdownEscapes(value, versionTwo) {
+    let protectedText = "";
+    for (let index = 0; index < value.length; index += 1) {
+        const character = value[index];
+        const escapedCharacter = value[index + 1];
+        if (character === "\\" &&
+            escapedCharacter !== undefined &&
+            (versionTwo
+                ? escapedCharacter.charCodeAt(0) >= 1 && escapedCharacter.charCodeAt(0) <= 0x7e
+                : "*_[]`".includes(escapedCharacter))) {
+            protectedText += "\0";
+            index += 1;
+            continue;
+        }
+        protectedText += character;
+    }
+    return protectedText;
+}
+function telegramMarkdownLiteralMask(value) {
+    return "\0".repeat(value.length);
+}
+function stripTelegramMarkdownExpandableMarker(line) {
+    if (!line.endsWith("||")) {
+        return line;
+    }
+    let markers = 0;
+    for (let index = line.indexOf("||"); index >= 0; index = line.indexOf("||", index + 2)) {
+        markers += 1;
+    }
+    return markers % 2 === 1 ? line.slice(0, -2) : line;
+}
+function telegramMarkdownText(value, versionTwo) {
+    let parsed = protectTelegramMarkdownEscapes(value, versionTwo)
+        .replace(/```(?:[^\n]*\n)?([\s\S]*?)```/gu, (_match, content) => telegramMarkdownLiteralMask(content))
+        .replace(/`([^`\n]*)`/gu, (_match, content) => telegramMarkdownLiteralMask(content))
+        .replace(/!\[([^\]\n]+)\]\(tg:\/\/(?:emoji\?id=\d+|time\?unix=-?\d+(?:&format=[rwdDtT]+)?)\)/gu, "$1")
+        .replace(/\[([^\]\n]+)\]\((?:\\.|[^)\n])*\)/gu, "$1");
+    if (versionTwo) {
+        parsed = parsed
+            .replace(/^(?:\*\*)?>[^\n]*$/gmu, stripTelegramMarkdownExpandableMarker)
+            .replace(/^\*\*(?=>)/gmu, "")
+            .replace(/^>/gmu, "")
+            .replace(/\|\|([\s\S]*?)\|\|/gu, "$1")
+            .replace(/__([\s\S]*?)__/gu, "$1")
+            .replace(/~([\s\S]*?)~/gu, "$1");
+    }
+    let previous;
+    do {
+        previous = parsed;
+        parsed = parsed.replace(/\*([\s\S]*?)\*/gu, "$1").replace(/_([\s\S]*?)_/gu, "$1");
+    } while (parsed !== previous);
+    return parsed;
+}
 function hasValidExplicitTelegramIdentities(body) {
     return ([body.chatId, body.chat_id].every((value) => value === undefined || telegramChatId(value) !== undefined) &&
         [
@@ -336,8 +1272,6 @@ function hasValidExplicitTelegramIdentities(body) {
             body.from_id,
             body.messageId,
             body.message_id,
-            body.messageThreadId,
-            body.message_thread_id,
             body.updateId,
             body.update_id,
         ].every((value) => value === undefined || toIntegerValue(value) !== undefined));
@@ -348,14 +1282,17 @@ function isValidIgnoredTelegramUpdate(body) {
     if (isJsonObject(body.message)) {
         const message = body.message;
         const chat = isJsonObject(message.chat) ? message.chat : undefined;
+        const messageId = toIntegerValue(message.message_id);
         if (updateId === undefined ||
+            updateId < 1 ||
             !chat ||
-            telegramChatId(chat.id) === undefined ||
-            toIntegerValue(message.message_id) === undefined ||
+            telegramStoredChatId(chat.id) === undefined ||
+            messageId === undefined ||
+            messageId < 0 ||
             (message.from !== undefined &&
-                (!isJsonObject(message.from) || toIntegerValue(message.from.id) === undefined)) ||
+                (!isJsonObject(message.from) || (toIntegerValue(message.from.id) ?? 0) < 1)) ||
             (message.message_thread_id !== undefined &&
-                toIntegerValue(message.message_thread_id) === undefined)) {
+                telegramMessageThreadId(message.message_thread_id) === undefined)) {
             return false;
         }
         return toStringValue(message.text) === undefined;
@@ -378,13 +1315,55 @@ async function handleTelegramAdminInbound(params) {
     });
     await previousAdmission;
     try {
-        const nextMessageId = params.state.nextMessageId;
         const nextUpdateId = params.state.nextUpdateId;
+        const explicitMessageId = explicitTelegramId(params.body, ["messageId", "message_id"], explicitTelegramMessageIdValues(params.body), { allowZero: true });
+        const explicitMessageChatId = explicitTelegramMessageChatId(params.body);
+        const explicitUpdateId = explicitTelegramId(params.body, ["updateId", "update_id"]);
+        const referencedMessageId = explicitTelegramId({}, [], referencedTelegramMessageIdValues(params.body));
+        const topLevelChatId = resolveTelegramChat(params.state, params.body.chatId ?? params.body.chat_id)?.id;
+        const messageChatId = explicitMessageChatId === false ? undefined : (explicitMessageChatId ?? topLevelChatId);
+        const messageChatKey = messageChatId === undefined ? undefined : telegramChatKey(messageChatId);
+        const previousNextMessageId = messageChatKey === undefined ? undefined : params.state.nextMessageIds.get(messageChatKey);
+        const nextMessageId = messageChatId === undefined ? undefined : nextTelegramMessageId(params.state, messageChatId);
+        if (!hasValidTelegramMessageThreadIds(params.body) ||
+            !hasValidTelegramTopicDestinations(params.state, params.body) ||
+            explicitMessageId === undefined ||
+            explicitMessageChatId === false ||
+            explicitUpdateId === undefined ||
+            referencedMessageId === undefined ||
+            (explicitMessageId.present &&
+                explicitMessageId.value > 0 &&
+                (nextMessageId === undefined || explicitMessageId.value < nextMessageId)) ||
+            (explicitUpdateId.present && explicitUpdateId.value < nextUpdateId)) {
+            return telegramError("Bad Request: explicit IDs must be valid and monotonic");
+        }
         const update = createInboundUpdate(params.state, params.body);
-        params.state.nextMessageId = nextMessageId;
         params.state.nextUpdateId = nextUpdateId;
+        if (update &&
+            ((!explicitMessageId.present &&
+                (nextMessageId ?? Number.MAX_SAFE_INTEGER) >= Number.MAX_SAFE_INTEGER) ||
+                (!explicitUpdateId.present && nextUpdateId >= Number.MAX_SAFE_INTEGER))) {
+            return telegramError("Bad Request: generated ID space is exhausted");
+        }
         if (!update) {
             if (isValidIgnoredTelegramUpdate(params.body)) {
+                if (messageChatKey !== undefined) {
+                    const observedNextMessageIds = [
+                        ...(explicitMessageId.present && explicitMessageId.value > 0
+                            ? [explicitMessageId.value + 1]
+                            : []),
+                        ...(referencedMessageId.present && referencedMessageId.value > 0
+                            ? [referencedMessageId.value + 1]
+                            : []),
+                    ];
+                    if (observedNextMessageIds.length > 0) {
+                        params.state.nextMessageIds.set(messageChatKey, Math.max(params.state.nextMessageIds.get(messageChatKey) ?? 1, ...observedNextMessageIds));
+                    }
+                }
+                if (explicitUpdateId.present) {
+                    params.state.nextUpdateId = explicitUpdateId.value + 1;
+                }
+                registerTelegramUpdateChats(params.state, params.body);
                 return jsonResponse({ ok: true });
             }
             return telegramError("Bad Request: chatId and text are required");
@@ -392,9 +1371,12 @@ async function handleTelegramAdminInbound(params) {
         if (params.state.updates.length >= params.state.maxPendingInboundEvents) {
             return telegramError(`Too Many Requests: pending inbound queue is full (${params.state.maxPendingInboundEvents} updates)`, 429);
         }
-        params.state.nextMessageId = Math.max(params.state.nextMessageId, update.message.message_id + 1);
+        const updateChatKey = telegramChatKey(update.message.chat.id);
+        params.state.nextMessageIds.set(updateChatKey, Math.max(params.state.nextMessageIds.get(updateChatKey) ?? 1, update.message.message_id + 1, ...(referencedMessageId.present && referencedMessageId.value > 0
+            ? [referencedMessageId.value + 1]
+            : [])));
         params.state.nextUpdateId = Math.max(params.state.nextUpdateId, update.update_id + 1);
-        const reservedNextMessageId = params.state.nextMessageId;
+        const reservedNextMessageId = params.state.nextMessageIds.get(updateChatKey);
         const reservedNextUpdateId = params.state.nextUpdateId;
         try {
             await appendEvent(params.state, {
@@ -407,14 +1389,20 @@ async function handleTelegramAdminInbound(params) {
             });
         }
         catch (error) {
-            if (params.state.nextMessageId === reservedNextMessageId) {
-                params.state.nextMessageId = nextMessageId;
+            if (params.state.nextMessageIds.get(updateChatKey) === reservedNextMessageId) {
+                if (previousNextMessageId === undefined) {
+                    params.state.nextMessageIds.delete(updateChatKey);
+                }
+                else {
+                    params.state.nextMessageIds.set(updateChatKey, previousNextMessageId);
+                }
             }
             if (params.state.nextUpdateId === reservedNextUpdateId) {
                 params.state.nextUpdateId = nextUpdateId;
             }
             throw error;
         }
+        registerTelegramChat(params.state, update.message.chat);
         params.state.updates.push(update);
         params.state.updates.sort((left, right) => left.update_id - right.update_id);
         if (params.state.webhook) {
@@ -690,14 +1678,29 @@ async function handleTelegramApi(params) {
             return telegramOk(createBotUser(params.state));
         case "setmycommands":
         case "deletemycommands":
-        case "sendchataction":
         case "answercallbackquery":
         case "deletemessage":
         case "pinchatmessage":
         case "unpinchatmessage":
         case "setmessagereaction":
-        case "editforumtopic":
             return telegramOk(true);
+        case "sendchataction": {
+            if (params.body.message_thread_id === undefined) {
+                return telegramOk(true);
+            }
+            const chat = resolveTelegramChat(params.state, params.body.chat_id);
+            const messageThreadId = telegramMessageThreadId(params.body.message_thread_id);
+            return chat && messageThreadId !== undefined && canTargetTelegramTopic(params.state, chat)
+                ? telegramOk(true)
+                : telegramError("Bad Request: chat is not a forum or message_thread_id is invalid");
+        }
+        case "editforumtopic": {
+            const chat = resolveTelegramChat(params.state, params.body.chat_id);
+            const messageThreadId = telegramMessageThreadId(params.body.message_thread_id);
+            return chat && messageThreadId !== undefined && canTargetTelegramTopic(params.state, chat)
+                ? telegramOk(true)
+                : telegramError("Bad Request: chat is not a forum or message_thread_id is invalid");
+        }
         case "setwebhook": {
             if (params.body.url === "") {
                 await replaceTelegramWebhook(params.state, undefined, toBooleanValue(params.body.drop_pending_updates));
@@ -717,6 +1720,15 @@ async function handleTelegramApi(params) {
             if (parsedUrl.protocol !== "http:" && parsedUrl.protocol !== "https:") {
                 return telegramError("Bad Request: bad webhook URL");
             }
+            const secretToken = params.body.secret_token === undefined
+                ? undefined
+                : typeof params.body.secret_token === "string"
+                    ? params.body.secret_token
+                    : null;
+            if (secretToken === null ||
+                (secretToken !== undefined && !TELEGRAM_WEBHOOK_SECRET_PATTERN.test(secretToken))) {
+                return telegramError("Bad Request: invalid secret token");
+            }
             if (params.state.activeWebhookValidations.size >= MAX_ACTIVE_TELEGRAM_WEBHOOK_VALIDATIONS) {
                 return telegramError("Too Many Requests: too many webhook validations", 429);
             }
@@ -728,10 +1740,6 @@ async function handleTelegramApi(params) {
             if (target instanceof Response) {
                 return target;
             }
-            const secretToken = toStringValue(params.body.secret_token);
-            if (secretToken && !/^[A-Za-z0-9_-]{1,256}$/u.test(secretToken)) {
-                return telegramError("Bad Request: invalid secret token");
-            }
             await replaceTelegramWebhook(params.state, {
                 ...(secretToken ? { secretToken } : {}),
                 url: parsedUrl.href,
@@ -753,20 +1761,50 @@ async function handleTelegramApi(params) {
                 pending_update_count: params.state.updates.length,
                 url: params.state.webhook?.url ?? "",
             });
-        case "createforumtopic":
+        case "createforumtopic": {
+            const chat = resolveTelegramChat(params.state, params.body.chat_id);
+            if (!chat) {
+                return telegramError("Bad Request: chat_id is required");
+            }
+            if (!canTargetTelegramTopic(params.state, chat)) {
+                return telegramError("Bad Request: chat is not a forum");
+            }
+            const messageThreadId = takeNextTelegramMessageId(params.state, chat.id);
+            if (messageThreadId === undefined) {
+                return telegramError("Bad Request: generated ID space is exhausted");
+            }
             return telegramOk({
                 icon_color: 0x6fb9f0,
-                message_thread_id: params.state.nextMessageId++,
+                message_thread_id: messageThreadId,
                 name: toStringValue(params.body.name) ?? "Crabline Topic",
             });
+        }
         case "editmessagetext": {
-            const message = createEditedMessage(params.state, params.body);
+            const text = readTelegramTextField(params.body.text, "text", {
+                parseMode: params.body.parse_mode,
+                required: true,
+            });
+            if (text instanceof Response) {
+                return text;
+            }
+            const message = createEditedMessage(params.state, params.body, text);
             return message
                 ? telegramOk(message)
                 : telegramError("Bad Request: chat_id, message_id, and text are required");
         }
         case "sendmessage": {
-            const message = createOutboundMessage(params.state, params.body);
+            const text = readTelegramTextField(params.body.text, "text", {
+                parseMode: params.body.parse_mode,
+                required: true,
+            });
+            if (text instanceof Response) {
+                return text;
+            }
+            const chat = resolveTelegramChat(params.state, params.body.chat_id);
+            if (chat && nextTelegramMessageId(params.state, chat.id) >= Number.MAX_SAFE_INTEGER) {
+                return telegramError("Bad Request: generated ID space is exhausted");
+            }
+            const message = createOutboundMessage(params.state, params.body, text);
             return message
                 ? telegramOk(message)
                 : telegramError("Bad Request: chat_id and text are required");
@@ -777,7 +1815,18 @@ async function handleTelegramApi(params) {
         case "sendphoto":
         case "sendvideo": {
             const mediaKind = method.slice("send".length);
-            const message = createOutboundMediaMessage(params.state, params.body, mediaKind);
+            const caption = readTelegramTextField(params.body.caption, "caption", {
+                parseMode: params.body.parse_mode,
+                required: false,
+            });
+            if (caption instanceof Response) {
+                return caption;
+            }
+            const chat = resolveTelegramChat(params.state, params.body.chat_id);
+            if (chat && nextTelegramMessageId(params.state, chat.id) >= Number.MAX_SAFE_INTEGER) {
+                return telegramError("Bad Request: generated ID space is exhausted");
+            }
+            const message = createOutboundMediaMessage(params.state, params.body, mediaKind, caption);
             return message
                 ? telegramOk(message)
                 : telegramError(`Bad Request: chat_id and ${mediaKind} are required`);
@@ -958,35 +2007,70 @@ async function handleRequest(params) {
         }
         return response;
     }
-    await appendEvent(params.state, event);
-    return await handleTelegramApi({
+    const response = await handleTelegramApi({
         body,
         method: botPath.method,
         request: params.request,
         state: params.state,
     });
+    event.accepted = response.ok;
+    await appendEvent(params.state, event);
+    return response;
+}
+async function serveRequest(params) {
+    let fetchResponse;
+    try {
+        fetchResponse = await handleRequest({ request: params.request, state: params.state });
+    }
+    catch (error) {
+        fetchResponse =
+            error instanceof InvalidJsonBodyError
+                ? telegramError("Bad Request: can't parse JSON object")
+                : error instanceof RequestBodyTooLargeError
+                    ? telegramError("Request Entity Too Large", 413)
+                    : jsonResponse({ error: "internal server error", ok: false }, 500);
+    }
+    try {
+        await writeResponse(params.response, fetchResponse);
+    }
+    catch {
+        // A disconnected client cannot receive an error fallback. End delivery here
+        // so the Node request callback never leaks an unhandled rejection.
+        params.response.destroy();
+    }
 }
 export async function startTelegramServer(params = {}) {
     const host = params.host ?? "127.0.0.1";
+    if (params.botHasTopicsEnabled !== undefined && typeof params.botHasTopicsEnabled !== "boolean") {
+        throw new Error("botHasTopicsEnabled must be a boolean.");
+    }
     const botId = params.botId ?? 424242;
     if (!Number.isSafeInteger(botId) || botId < 1) {
         throw new Error("botId must be a positive safe integer.");
     }
+    const botUsernameValue = params.botUsername ?? "crabline_bot";
+    const botUsername = botUsernameValue.trim().replace(/^@/u, "").toLowerCase();
+    if (!TELEGRAM_BOT_USERNAME_PATTERN.test(`@${botUsername}`)) {
+        throw new Error("botUsername must be a valid 5-32 character Telegram username.");
+    }
     const state = {
         activeUpdatePoll: undefined,
         activeWebhookDeliveries: new Set(),
         activeWebhookValidations: new Set(),
         adminToken: params.adminToken ?? randomBytes(24).toString("hex"),
         allowLoopbackHttpWebhook: isLoopbackHost(host),
+        botHasTopicsEnabled: params.botHasTopicsEnabled ?? true,
         botId,
         botToken: params.botToken ??
             (isLoopbackHost(host)
                 ? "424242:crabline-telegram-token"
                 : `${botId}:${randomBytes(26).toString("base64url")}`),
-        botUsername: params.botUsername ?? "crabline_bot",
+        botUsername,
+        chatsById: new Map(),
+        chatsByUsername: new Map(),
         inboundAdmission: Promise.resolve(),
         maxPendingInboundEvents: resolveMaxPendingInboundEvents(params.maxPendingInboundEvents),
-        nextMessageId: 1,
+        nextMessageIds: new Map(),
         nextUpdateId: 1,
         onEvent: params.onEvent,
         recorderPath: params.recorderPath ?? path.resolve(".crabline", "servers", "telegram.jsonl"),
@@ -1001,17 +2085,8 @@ export async function startTelegramServer(params = {}) {
         webhookRetryUpdateId: undefined,
     };
     const port = params.port ?? 0;
-    const server = createServer(async (request, response) => {
-        try {
-            await writeResponse(response, await handleRequest({ request, state }));
-        }
-        catch (error) {
-            await writeResponse(response, error instanceof InvalidJsonBodyError
-                ? telegramError("Bad Request: can't parse JSON object")
-                : error instanceof RequestBodyTooLargeError
-                    ? telegramError("Request Entity Too Large", 413)
-                    : jsonResponse({ error: "internal server error", ok: false }, 500));
-        }
+    const server = createServer((request, response) => {
+        void serveRequest({ request, response, state });
     });
     await new Promise((resolve, reject) => {
         server.once("error", reject);