@jant/core 0.5.3 → 0.6.0

package/src/lib/__tests__/telegram-pool-webhooks.test.ts

@@ -0,0 +1,127 @@
+import { describe, it, expect, afterEach, vi } from "vitest";
+import { registerTelegramPoolWebhooks } from "../telegram-pool-webhooks.js";
+
+const BOT_ID = "111111";
+const TOKEN = `${BOT_ID}:AA-test-token`;
+const BASE_URL = "https://cloud.example";
+const SECRET = "shared-webhook-secret";
+const EXPECTED_URL = `${BASE_URL}/api/telegram/webhook/${BOT_ID}`;
+
+interface Call {
+  method: string;
+  body: Record<string, unknown>;
+}
+
+/** Mocks the Telegram API; `currentWebhookUrl` is what getWebhookInfo reports. */
+function mockFetch(currentWebhookUrl: string): Call[] {
+  const calls: Call[] = [];
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async (url: string, init?: { body?: unknown }) => {
+      const method = String(url).split("/").pop() ?? "";
+      const body = init?.body ? JSON.parse(String(init.body)) : {};
+      calls.push({ method, body });
+      const result =
+        method === "getWebhookInfo" ? { url: currentWebhookUrl } : true;
+      return new Response(JSON.stringify({ ok: true, result }), {
+        headers: { "content-type": "application/json" },
+      });
+    }),
+  );
+  return calls;
+}
+
+describe("registerTelegramPoolWebhooks", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  it("does nothing when no pool is configured", async () => {
+    const calls = mockFetch("");
+    await registerTelegramPoolWebhooks({});
+    expect(calls).toHaveLength(0);
+  });
+
+  it("does nothing when not a hosted deployment", async () => {
+    const calls = mockFetch("");
+    await registerTelegramPoolWebhooks({
+      TELEGRAM_BOT_TOKENS: TOKEN,
+      TELEGRAM_WEBHOOK_SECRET: SECRET,
+    });
+    expect(calls).toHaveLength(0);
+  });
+
+  it("skips registration when the shared secret is missing", async () => {
+    const calls = mockFetch("");
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    await registerTelegramPoolWebhooks({
+      TELEGRAM_BOT_TOKENS: TOKEN,
+      HOSTED_CONTROL_PLANE_BASE_URL: BASE_URL,
+    });
+    expect(calls).toHaveLength(0);
+  });
+
+  it("registers a webhook that is not yet set", async () => {
+    const calls = mockFetch("");
+    vi.spyOn(console, "log").mockImplementation(() => {});
+    await registerTelegramPoolWebhooks({
+      TELEGRAM_BOT_TOKENS: TOKEN,
+      TELEGRAM_WEBHOOK_SECRET: SECRET,
+      HOSTED_CONTROL_PLANE_BASE_URL: BASE_URL,
+    });
+    expect(calls.map((c) => c.method)).toEqual([
+      "getWebhookInfo",
+      "setWebhook",
+      "setMyCommands",
+    ]);
+    expect(calls[1]?.body).toMatchObject({
+      url: EXPECTED_URL,
+      secret_token: SECRET,
+    });
+  });
+
+  it("skips setWebhook when already pointed at the right URL but still syncs commands", async () => {
+    const calls = mockFetch(EXPECTED_URL);
+    await registerTelegramPoolWebhooks({
+      TELEGRAM_BOT_TOKENS: TOKEN,
+      TELEGRAM_WEBHOOK_SECRET: SECRET,
+      HOSTED_CONTROL_PLANE_BASE_URL: BASE_URL,
+    });
+    expect(calls.map((c) => c.method)).toEqual([
+      "getWebhookInfo",
+      "setMyCommands",
+    ]);
+  });
+
+  it("re-registers when the webhook points elsewhere", async () => {
+    const calls = mockFetch(
+      "https://stale.example/api/telegram/webhook/111111",
+    );
+    vi.spyOn(console, "log").mockImplementation(() => {});
+    await registerTelegramPoolWebhooks({
+      TELEGRAM_BOT_TOKENS: TOKEN,
+      TELEGRAM_WEBHOOK_SECRET: SECRET,
+      HOSTED_CONTROL_PLANE_BASE_URL: BASE_URL,
+    });
+    expect(calls.map((c) => c.method)).toEqual([
+      "getWebhookInfo",
+      "setWebhook",
+      "setMyCommands",
+    ]);
+  });
+
+  it("registers /start in the command list so Telegram autocomplete works", async () => {
+    const calls = mockFetch("");
+    vi.spyOn(console, "log").mockImplementation(() => {});
+    await registerTelegramPoolWebhooks({
+      TELEGRAM_BOT_TOKENS: TOKEN,
+      TELEGRAM_WEBHOOK_SECRET: SECRET,
+      HOSTED_CONTROL_PLANE_BASE_URL: BASE_URL,
+    });
+    const setCommands = calls.find((c) => c.method === "setMyCommands");
+    expect(setCommands?.body).toMatchObject({
+      commands: [{ command: "start" }],
+    });
+  });
+});

package/src/lib/env.ts

@@ -301,6 +301,51 @@ export function shouldTrustProxy(env: EnvSource): boolean {
   return getEnvString(env, "TRUST_PROXY") === "true";
 }
 
+/** A single platform-managed Telegram bot from `TELEGRAM_BOT_TOKENS`. */
+export interface TelegramPoolBot {
+  /** Numeric bot id — the part before `:` in the token. */
+  botId: string;
+  /** Full `<bot_id>:<secret>` bot token. */
+  token: string;
+}
+
+/**
+ * Parses the platform-managed Telegram bot pool from `TELEGRAM_BOT_TOKENS`.
+ *
+ * The env value is a comma-separated list of `<bot_id>:<secret>` tokens. The
+ * first entry is the public-facing bot (`bot1`); the rest are surfaced only
+ * contextually when a binding code reaches an already-bound bot slot.
+ *
+ * @param env - Runtime environment bindings
+ * @returns Parsed pool bots in declared order; empty when unset/invalid
+ * @example
+ * getTelegramBotPool({ TELEGRAM_BOT_TOKENS: "111:aaa,222:bbb" });
+ */
+export function getTelegramBotPool(env: EnvSource): TelegramPoolBot[] {
+  const raw = getEnvString(env, "TELEGRAM_BOT_TOKENS");
+  if (!raw) {
+    return [];
+  }
+
+  return raw
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0)
+    .map((token) => {
+      const botId = token.split(":")[0]?.trim() ?? "";
+      return { botId, token };
+    })
+    .filter((bot) => bot.botId.length > 0);
+}
+
+/**
+ * Returns the shared `secret_token` used when registering every pool bot's
+ * webhook. Only meaningful alongside `TELEGRAM_BOT_TOKENS`.
+ */
+export function getTelegramWebhookSecret(env: EnvSource): string | undefined {
+  return getEnvString(env, "TELEGRAM_WEBHOOK_SECRET");
+}
+
 export function shouldUseSecureCookies(
   env: EnvSource,
   publicRequestUrl: string,

package/src/lib/ids.ts

@@ -16,6 +16,9 @@ export const ID_PREFIX = {
   session: "ses",
   account: "acc",
   verification: "vrf",
+  telegramBinding: "tgb",
+  telegramBindingCode: "tgc",
+  telegramMediaGroupItem: "tmg",
 } as const;
 
 export type IdPrefix = (typeof ID_PREFIX)[keyof typeof ID_PREFIX];

package/src/lib/image-dimensions.ts

@@ -0,0 +1,258 @@
+/**
+ * Parse intrinsic pixel dimensions from a raw image header buffer.
+ *
+ * Used as a server-side fallback when an upload client does not provide
+ * `width` / `height`. Only the file header is needed — typically the first
+ * few hundred bytes for PNG/JPEG/GIF/WebP, and up to ~64 KB for AVIF where
+ * the `ispe` property can be nested inside a larger `meta` box.
+ *
+ * Returns `null` when the bytes are too short, the format is unsupported,
+ * or the header is malformed.
+ *
+ * @param mimeType MIME type the upload was declared as (e.g. `image/png`).
+ * @param bytes Bytes from the start of the file. Pass at least
+ *   {@link IMAGE_DIMENSION_PEEK_BYTES} for AVIF reliability; smaller is fine
+ *   for other formats.
+ */
+export function parseImageDimensions(
+  mimeType: string,
+  bytes: Uint8Array,
+): { width: number; height: number } | null {
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  switch (mimeType) {
+    case "image/png":
+      return parsePng(view);
+    case "image/jpeg":
+    case "image/jpg":
+      return parseJpeg(view);
+    case "image/gif":
+      return parseGif(view);
+    case "image/webp":
+      return parseWebp(view);
+    case "image/avif":
+      return parseIsoBmff(view, new Set(["avif", "avis"]));
+    default:
+      return null;
+  }
+}
+
+/**
+ * Recommended number of header bytes to feed into {@link parseImageDimensions}.
+ *
+ * Covers AVIF files with EXIF/ICC properties placed before the `ispe` box.
+ * Smaller formats only inspect the first ~30 bytes.
+ */
+export const IMAGE_DIMENSION_PEEK_BYTES = 64 * 1024;
+
+function readChars(view: DataView, offset: number, length: number): string {
+  let out = "";
+  for (let i = 0; i < length; i += 1) {
+    out += String.fromCharCode(view.getUint8(offset + i));
+  }
+  return out;
+}
+
+function parsePng(view: DataView): { width: number; height: number } | null {
+  if (view.byteLength < 24) return null;
+  const signature = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+  for (let i = 0; i < 8; i += 1) {
+    if (view.getUint8(i) !== signature[i]) return null;
+  }
+  const width = view.getUint32(16, false);
+  const height = view.getUint32(20, false);
+  if (width === 0 || height === 0) return null;
+  return { width, height };
+}
+
+function parseGif(view: DataView): { width: number; height: number } | null {
+  if (view.byteLength < 10) return null;
+  if (
+    view.getUint8(0) !== 0x47 ||
+    view.getUint8(1) !== 0x49 ||
+    view.getUint8(2) !== 0x46
+  ) {
+    return null;
+  }
+  const width = view.getUint16(6, true);
+  const height = view.getUint16(8, true);
+  if (width === 0 || height === 0) return null;
+  return { width, height };
+}
+
+function parseWebp(view: DataView): { width: number; height: number } | null {
+  if (view.byteLength < 16) return null;
+  if (readChars(view, 0, 4) !== "RIFF") return null;
+  if (readChars(view, 8, 4) !== "WEBP") return null;
+  const chunk = readChars(view, 12, 4);
+
+  if (chunk === "VP8 ") {
+    if (view.byteLength < 30) return null;
+    if (
+      view.getUint8(23) !== 0x9d ||
+      view.getUint8(24) !== 0x01 ||
+      view.getUint8(25) !== 0x2a
+    ) {
+      return null;
+    }
+    const width = view.getUint16(26, true) & 0x3fff;
+    const height = view.getUint16(28, true) & 0x3fff;
+    if (width === 0 || height === 0) return null;
+    return { width, height };
+  }
+
+  if (chunk === "VP8L") {
+    if (view.byteLength < 25) return null;
+    if (view.getUint8(20) !== 0x2f) return null;
+    const b0 = view.getUint8(21);
+    const b1 = view.getUint8(22);
+    const b2 = view.getUint8(23);
+    const b3 = view.getUint8(24);
+    const width = 1 + (((b1 & 0x3f) << 8) | b0);
+    const height = 1 + (((b3 & 0x0f) << 10) | (b2 << 2) | ((b1 & 0xc0) >> 6));
+    return { width, height };
+  }
+
+  if (chunk === "VP8X") {
+    if (view.byteLength < 30) return null;
+    const width =
+      1 +
+      (view.getUint8(24) |
+        (view.getUint8(25) << 8) |
+        (view.getUint8(26) << 16));
+    const height =
+      1 +
+      (view.getUint8(27) |
+        (view.getUint8(28) << 8) |
+        (view.getUint8(29) << 16));
+    return { width, height };
+  }
+
+  return null;
+}
+
+function parseJpeg(view: DataView): { width: number; height: number } | null {
+  const length = view.byteLength;
+  if (length < 4) return null;
+  if (view.getUint8(0) !== 0xff || view.getUint8(1) !== 0xd8) return null;
+
+  let i = 2;
+  while (i < length) {
+    while (i < length && view.getUint8(i) !== 0xff) i += 1;
+    while (i < length && view.getUint8(i) === 0xff) i += 1;
+    if (i >= length) return null;
+    const marker = view.getUint8(i);
+    i += 1;
+
+    // Standalone markers without a payload length: 0x00 (escaped FF),
+    // 0x01 (TEM), 0xD0–0xD9 (RSTn / SOI / EOI).
+    if (marker === 0x00 || marker === 0x01) continue;
+    if (marker >= 0xd0 && marker <= 0xd9) continue;
+
+    if (i + 2 > length) return null;
+    const segLen = view.getUint16(i, false);
+    if (segLen < 2) return null;
+
+    const isStartOfFrame =
+      (marker >= 0xc0 && marker <= 0xc3) ||
+      (marker >= 0xc5 && marker <= 0xc7) ||
+      (marker >= 0xc9 && marker <= 0xcb) ||
+      (marker >= 0xcd && marker <= 0xcf);
+
+    if (isStartOfFrame) {
+      // SOF payload: length(2) precision(1) height(2) width(2) components(1)
+      if (i + 7 > length) return null;
+      const height = view.getUint16(i + 3, false);
+      const width = view.getUint16(i + 5, false);
+      if (width === 0 || height === 0) return null;
+      return { width, height };
+    }
+
+    i += segLen;
+  }
+  return null;
+}
+
+interface IsoBox {
+  size: number;
+  type: string;
+  payloadOffset: number;
+  end: number;
+}
+
+function readBox(view: DataView, pos: number): IsoBox | null {
+  if (pos + 8 > view.byteLength) return null;
+  let size = view.getUint32(pos, false);
+  const type = readChars(view, pos + 4, 4);
+  if (size === 1) {
+    // 64-bit largesize: we don't bother — the dimension boxes we need fit in
+    // the first 64 KB of any sane image.
+    return null;
+  }
+  if (size === 0) {
+    size = view.byteLength - pos;
+  }
+  if (size < 8) return null;
+  return { size, type, payloadOffset: pos + 8, end: pos + size };
+}
+
+function findChild(
+  view: DataView,
+  start: number,
+  end: number,
+  type: string,
+): IsoBox | null {
+  let pos = start;
+  while (pos < end) {
+    const box = readBox(view, pos);
+    if (!box) return null;
+    if (box.type === type) return box;
+    pos = box.end;
+  }
+  return null;
+}
+
+function parseIsoBmff(
+  view: DataView,
+  acceptedBrands: Set<string>,
+): { width: number; height: number } | null {
+  const ftyp = readBox(view, 0);
+  if (!ftyp || ftyp.type !== "ftyp") return null;
+
+  // major_brand at payloadOffset, minor_version at +4, compatible_brands from +8
+  let isAccepted = false;
+  if (ftyp.payloadOffset + 4 <= ftyp.end) {
+    isAccepted = acceptedBrands.has(readChars(view, ftyp.payloadOffset, 4));
+  }
+  for (
+    let q = ftyp.payloadOffset + 8;
+    !isAccepted && q + 4 <= ftyp.end;
+    q += 4
+  ) {
+    if (acceptedBrands.has(readChars(view, q, 4))) {
+      isAccepted = true;
+    }
+  }
+  if (!isAccepted) return null;
+
+  const meta = findChild(view, ftyp.end, view.byteLength, "meta");
+  if (!meta) return null;
+
+  // meta is a FullBox: skip the 4-byte version/flags before its children.
+  const iprp = findChild(view, meta.payloadOffset + 4, meta.end, "iprp");
+  if (!iprp) return null;
+
+  const ipco = findChild(view, iprp.payloadOffset, iprp.end, "ipco");
+  if (!ipco) return null;
+
+  // The first ispe inside ipco describes the primary image.
+  const ispe = findChild(view, ipco.payloadOffset, ipco.end, "ispe");
+  if (!ispe) return null;
+
+  // ispe is a FullBox: version(1) flags(3) width(4) height(4)
+  const widthOffset = ispe.payloadOffset + 4;
+  if (widthOffset + 8 > view.byteLength) return null;
+  const width = view.getUint32(widthOffset, false);
+  const height = view.getUint32(widthOffset + 4, false);
+  if (width === 0 || height === 0) return null;
+  return { width, height };
+}

package/src/lib/mp4-track-flags.ts

@@ -0,0 +1,71 @@
+/**
+ * In-place patching of MP4 track header (`tkhd`) flags.
+ *
+ * Mediabunny's MP4 muxer writes a non-zero `alternate_group` into every
+ * `tkhd` box (video → 1, audio → 2). Per ISO-BMFF, a non-zero
+ * `alternate_group` marks a track as one of several mutually exclusive
+ * alternates. Safari's native `<video>` player reacts to this by never
+ * auto-hiding the control bar during playback — the controls stay pinned.
+ * ffmpeg writes 0 here; matching that restores normal control-bar behavior.
+ */
+
+/** ISO-BMFF container boxes that hold a `tkhd` somewhere below them. */
+const CONTAINER_TYPES = new Set(["moov", "trak"]);
+
+/**
+ * Byte offset of the `alternate_group` field within a `tkhd` box, measured
+ * from the start of the box. The field sits after the box header, the
+ * version/flags word, the (version-sized) time/duration fields, the two
+ * reserved words, and the 2-byte `layer` field.
+ */
+function alternateGroupOffset(version: number): number {
+  // header(8) + version/flags(4) + variable middle + reserved(8) + layer(2):
+  //   v0: creation(4) modification(4) trackID(4) reserved(4) duration(4) = 20
+  //   v1: creation(8) modification(8) trackID(4) reserved(4) duration(8) = 32
+  return 8 + 4 + (version === 1 ? 32 : 20) + 8 + 2;
+}
+
+/**
+ * Zero the `alternate_group` field of every `tkhd` box in an MP4 buffer,
+ * operating in place. Safe to call on any ISO-BMFF file; boxes without a
+ * `tkhd` are left untouched.
+ *
+ * @param buffer - The MP4 file bytes. Mutated in place.
+ * @example
+ * zeroTrackAlternateGroups(mediabunnyOutput);
+ */
+export function zeroTrackAlternateGroups(buffer: ArrayBuffer): void {
+  const view = new DataView(buffer);
+
+  const walk = (start: number, end: number): void => {
+    let pos = start;
+    while (pos + 8 <= end) {
+      let size = view.getUint32(pos);
+      const type = String.fromCharCode(
+        view.getUint8(pos + 4),
+        view.getUint8(pos + 5),
+        view.getUint8(pos + 6),
+        view.getUint8(pos + 7),
+      );
+      if (size === 0) size = end - pos;
+      if (size < 8 || pos + size > end) break;
+
+      if (type === "tkhd") {
+        const version = view.getUint8(pos + 8);
+        const fieldOffset = pos + alternateGroupOffset(version);
+        if (
+          fieldOffset + 2 <= pos + size &&
+          view.getUint16(fieldOffset) !== 0
+        ) {
+          view.setUint16(fieldOffset, 0);
+        }
+      } else if (CONTAINER_TYPES.has(type)) {
+        walk(pos + 8, pos + size);
+      }
+
+      pos += size;
+    }
+  };
+
+  walk(0, buffer.byteLength);
+}