@botcord/daemon 0.2.35 → 0.2.37

package/src/gateway/channels/telegram.ts

@@ -0,0 +1,469 @@
+import type {
+  ChannelAdapter,
+  ChannelSendContext,
+  ChannelSendResult,
+  ChannelStartContext,
+  ChannelStatusSnapshot,
+  ChannelStopContext,
+  ChannelTypingContext,
+  GatewayInboundEnvelope,
+  GatewayInboundMessage,
+} from "../types.js";
+import { sanitizeUntrustedContent } from "./sanitize.js";
+import { GatewayStateStore } from "./state-store.js";
+import { loadGatewaySecret } from "./secret-store.js";
+import { splitText } from "./text-split.js";
+
+const DEFAULT_BASE_URL = "https://api.telegram.org";
+const DEFAULT_SPLIT_AT = 4000; // Telegram hard limit is 4096; leave slack.
+const POLL_TIMEOUT_S = 25;
+const POLL_BACKOFF_MS = 3000;
+const TRANSIENT_BACKOFF_MS = 1000;
+const TELEGRAM_PROVIDER = "telegram" as const;
+
+/** Options accepted by {@link createTelegramChannel}. */
+export interface TelegramChannelOptions {
+  id: string;
+  accountId: string;
+  /** Bot token. When omitted, the adapter loads it from the secret-store on start. */
+  botToken?: string;
+  baseUrl?: string;
+  /** Empty / missing list = default-deny. */
+  allowedSenderIds?: string[];
+  /** Empty / missing list = default-deny. */
+  allowedChatIds?: string[];
+  splitAt?: number;
+  secretFile?: string;
+  stateFile?: string;
+  /** Test hook: override `globalThis.fetch`. */
+  fetchImpl?: typeof fetch;
+  /** Test hook: synchronous state writes (`debounceMs: 0`). */
+  stateDebounceMs?: number;
+}
+
+interface TelegramSecret {
+  botToken?: string;
+  [key: string]: unknown;
+}
+
+interface TelegramUser {
+  id: number;
+  is_bot?: boolean;
+  username?: string;
+  first_name?: string;
+}
+
+interface TelegramChat {
+  id: number;
+  type: "private" | "group" | "supergroup" | "channel";
+  title?: string;
+}
+
+interface TelegramMessage {
+  message_id: number;
+  from?: TelegramUser;
+  chat: TelegramChat;
+  text?: string;
+  date?: number;
+}
+
+interface TelegramUpdate {
+  update_id: number;
+  message?: TelegramMessage;
+}
+
+interface TelegramApiResult<T> {
+  ok: boolean;
+  result?: T;
+  description?: string;
+}
+
+/**
+ * Telegram channel adapter — long-polls `getUpdates`, normalizes text messages
+ * to `GatewayInboundEnvelope`, and writes replies via `sendMessage`. Cursor
+ * (`update_id + 1`) is persisted to the state-store so a daemon restart never
+ * replays the last batch.
+ *
+ * Allowlists are default-deny: an empty (or missing) `allowedChatIds` /
+ * `allowedSenderIds` rejects every inbound message. This matches the security
+ * default in the third-party-gateway design doc.
+ */
+export function createTelegramChannel(opts: TelegramChannelOptions): ChannelAdapter {
+  const channelType = TELEGRAM_PROVIDER;
+  const baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+  const splitAt = opts.splitAt && opts.splitAt > 0 ? opts.splitAt : DEFAULT_SPLIT_AT;
+  const allowedSenderIds = new Set((opts.allowedSenderIds ?? []).map((s) => String(s)));
+  const allowedChatIds = new Set((opts.allowedChatIds ?? []).map((s) => String(s)));
+  const fetchImpl: typeof fetch = opts.fetchImpl ?? globalThis.fetch.bind(globalThis);
+
+  let botToken: string | undefined = opts.botToken;
+  let started = false;
+
+  /**
+   * C3: Redact the bot token from any log/error string. Telegram's Bot API
+   * embeds the token in the URL path, so fetch errors and JSON.parse failures
+   * routinely include it. Replace before any log.* call.
+   */
+  function redactToken(input: string): string {
+    if (!botToken || !input) return input;
+    return input.split(botToken).join("***");
+  }
+  let stateStore: GatewayStateStore | null = null;
+  let stopCallback: (() => void) | null = null;
+  // W11: captured during start() so send() can push lastSendAt to the
+  // gateway-tracked snapshot, not just the local statusSnapshot.
+  let liveSetStatus:
+    | ((patch: Partial<ChannelStatusSnapshot>) => void)
+    | null = null;
+
+  let statusSnapshot: ChannelStatusSnapshot = {
+    channel: opts.id,
+    accountId: opts.accountId,
+    running: false,
+    connected: false,
+    reconnectAttempts: 0,
+    lastError: null,
+    provider: TELEGRAM_PROVIDER,
+    authorized: false,
+  };
+
+  function ensureState(): GatewayStateStore {
+    if (!stateStore) {
+      stateStore = new GatewayStateStore(opts.id, {
+        ...(opts.stateFile ? { override: opts.stateFile } : {}),
+        ...(opts.stateDebounceMs !== undefined
+          ? { debounceMs: opts.stateDebounceMs }
+          : {}),
+      });
+    }
+    return stateStore;
+  }
+
+  function loadTokenFromSecretIfNeeded(): string | undefined {
+    if (botToken) return botToken;
+    const secret = loadGatewaySecret<TelegramSecret>(opts.id, opts.secretFile);
+    if (secret && typeof secret.botToken === "string" && secret.botToken.length > 0) {
+      botToken = secret.botToken;
+    }
+    return botToken;
+  }
+
+  async function callApi<T>(
+    method: string,
+    params: Record<string, unknown>,
+    timeoutMs: number,
+  ): Promise<TelegramApiResult<T>> {
+    if (!botToken) throw new Error("telegram bot token not loaded");
+    const url = `${baseUrl}/bot${botToken}/${method}`;
+    let resp: Response;
+    try {
+      resp = await fetchImpl(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(params),
+        signal: AbortSignal.timeout(timeoutMs),
+      });
+    } catch (err) {
+      // C3: fetch errors often stringify the URL (which embeds the token).
+      // Re-raise with the token replaced.
+      const e = err as Error;
+      const redacted = redactToken(e.message ?? String(err));
+      const next = new Error(redacted);
+      next.name = e.name ?? "Error";
+      throw next;
+    }
+    const json = (await resp.json()) as TelegramApiResult<T>;
+    return json;
+  }
+
+  function chatIdFromConversation(conversationId: string): string | null {
+    if (conversationId.startsWith("telegram:user:")) {
+      return conversationId.slice("telegram:user:".length);
+    }
+    if (conversationId.startsWith("telegram:group:")) {
+      return conversationId.slice("telegram:group:".length);
+    }
+    return null;
+  }
+
+  function normalizeUpdate(update: TelegramUpdate): GatewayInboundMessage | null {
+    const msg = update.message;
+    if (!msg) return null;
+    const text = typeof msg.text === "string" ? msg.text : null;
+    if (text === null) return null;
+    const from = msg.from;
+    if (!from) return null;
+    const chat = msg.chat;
+    if (!chat) return null;
+
+    const fromUserId = String(from.id);
+    const chatId = String(chat.id);
+
+    // W5: default-deny is the INTERSECTION — both chatId AND senderId must
+    // appear in their respective allowlists. An empty list rejects everyone.
+    // TODO: surface this rule in the dashboard help text (frontend).
+    if (!allowedChatIds.has(chatId)) return null;
+    if (!allowedSenderIds.has(fromUserId)) return null;
+
+    const isPrivate = chat.type === "private";
+    const conversationId = isPrivate
+      ? `telegram:user:${chatId}`
+      : `telegram:group:${chatId}`;
+    const conversationKind: "direct" | "group" = isPrivate ? "direct" : "group";
+
+    const senderName =
+      from.username ??
+      [from.first_name].filter((s): s is string => typeof s === "string" && s.length > 0)[0];
+
+    const sanitized = sanitizeUntrustedContent(text);
+    const messageId = `telegram:${chatId}:${msg.message_id}`;
+
+    return {
+      id: messageId,
+      channel: opts.id,
+      accountId: opts.accountId,
+      conversation: {
+        id: conversationId,
+        kind: conversationKind,
+        ...(chat.title ? { title: chat.title } : {}),
+      },
+      sender: {
+        id: `telegram:user:${fromUserId}`,
+        ...(senderName ? { name: senderName } : {}),
+        kind: "user",
+      },
+      text: sanitized,
+      raw: update,
+      replyTo: null,
+      mentioned: false,
+      receivedAt: Date.now(),
+      trace: { id: messageId, streamable: false },
+    };
+  }
+
+  async function pollLoop(ctx: ChannelStartContext): Promise<void> {
+    const { abortSignal, log, emit, setStatus } = ctx;
+    liveSetStatus = setStatus;
+    const state = ensureState();
+
+    function markStatus(patch: Partial<ChannelStatusSnapshot>) {
+      statusSnapshot = { ...statusSnapshot, ...patch };
+      setStatus(patch);
+    }
+
+    if (!loadTokenFromSecretIfNeeded()) {
+      markStatus({
+        running: false,
+        connected: false,
+        authorized: false,
+        lastError: "missing_secret",
+      });
+      log.error("telegram missing bot token", { gatewayId: opts.id });
+      return;
+    }
+
+    let offset = 0;
+    const cursor = state.getCursor();
+    if (cursor) {
+      const parsed = Number(cursor);
+      if (Number.isFinite(parsed)) offset = parsed;
+    }
+
+    markStatus({
+      running: true,
+      connected: true,
+      authorized: true,
+      reconnectAttempts: 0,
+      lastError: null,
+      lastStartAt: Date.now(),
+    });
+    log.info("telegram poll loop starting", { gatewayId: opts.id, offset });
+
+    let stopped = false;
+    const onAbort = () => {
+      stopped = true;
+    };
+    abortSignal.addEventListener("abort", onAbort, { once: true });
+    stopCallback = () => {
+      stopped = true;
+    };
+
+    while (!stopped && !abortSignal.aborted) {
+      try {
+        const resp = await callApi<TelegramUpdate[]>(
+          "getUpdates",
+          {
+            offset,
+            timeout: POLL_TIMEOUT_S,
+            allowed_updates: ["message"],
+          },
+          (POLL_TIMEOUT_S + 15) * 1000,
+        );
+        markStatus({ lastPollAt: Date.now() });
+        if (!resp.ok) {
+          log.warn("telegram getUpdates non-ok", {
+            description: redactToken(resp.description ?? ""),
+          });
+          markStatus({ lastError: redactToken(resp.description ?? "getUpdates failed") });
+          await sleep(POLL_BACKOFF_MS, abortSignal);
+          continue;
+        }
+        const updates = resp.result ?? [];
+        if (updates.length === 0) continue;
+
+        // W1: persist cursor only AFTER all emits return cleanly. If emit
+        // throws, leave the cursor untouched so the same batch retries on
+        // the next poll instead of being silently dropped.
+        let maxId = offset - 1;
+        for (const u of updates) {
+          if (u.update_id > maxId) maxId = u.update_id;
+        }
+
+        let emitFailed = false;
+        for (const update of updates) {
+          const normalized = normalizeUpdate(update);
+          if (!normalized) continue;
+          markStatus({ lastInboundAt: Date.now() });
+          const envelope: GatewayInboundEnvelope = { message: normalized };
+          try {
+            await emit(envelope);
+          } catch (err) {
+            emitFailed = true;
+            log.error("telegram emit threw — leaving cursor unchanged", {
+              err: redactToken(String(err)),
+            });
+            break;
+          }
+        }
+        if (!emitFailed) {
+          offset = maxId + 1;
+          state.update({ cursor: String(offset) });
+        }
+      } catch (err) {
+        if (stopped || abortSignal.aborted) break;
+        const name = (err as Error)?.name ?? "";
+        if (name === "AbortError" || name === "TimeoutError") {
+          log.warn("telegram poll transient", { name });
+          await sleep(TRANSIENT_BACKOFF_MS, abortSignal);
+          continue;
+        }
+        log.error("telegram poll failed", { err: redactToken(String(err)) });
+        markStatus({ lastError: redactToken(String(err)) });
+        await sleep(POLL_BACKOFF_MS, abortSignal);
+      }
+    }
+
+    markStatus({
+      running: false,
+      connected: false,
+      lastStopAt: Date.now(),
+    });
+    try {
+      state.flush();
+    } catch (e) {
+      log.warn("state-flush-on-stop failed", { error: String(e) });
+    }
+  }
+
+  const adapter: ChannelAdapter = {
+    id: opts.id,
+    type: channelType,
+
+    async start(ctx: ChannelStartContext): Promise<void> {
+      if (started) throw new Error("already started");
+      started = true;
+      await pollLoop(ctx);
+    },
+
+    async stop(_ctx: ChannelStopContext): Promise<void> {
+      if (stopCallback) {
+        stopCallback();
+        stopCallback = null;
+      }
+      try {
+        stateStore?.flush();
+      } catch (e) {
+        // W7: log flush failures at stop — previously swallowed silently.
+        console.warn("[telegram] state-flush-on-stop failed", String(e));
+      }
+    },
+
+    async send(ctx: ChannelSendContext): Promise<ChannelSendResult> {
+      const { message, log } = ctx;
+      if (!loadTokenFromSecretIfNeeded()) {
+        throw new Error("telegram bot token not loaded");
+      }
+      const chatId = chatIdFromConversation(message.conversationId);
+      if (!chatId) {
+        throw new Error(
+          `telegram send: unrecognized conversationId "${message.conversationId}"`,
+        );
+      }
+      const chunks = splitText(message.text, splitAt);
+      let lastMessageId: string | null = null;
+      for (const chunk of chunks) {
+        const resp = await callApi<TelegramMessage>(
+          "sendMessage",
+          {
+            chat_id: chatId,
+            text: chunk,
+            disable_web_page_preview: true,
+          },
+          15_000,
+        );
+        if (!resp.ok) {
+          log.warn("telegram sendMessage non-ok", {
+            description: redactToken(resp.description ?? ""),
+          });
+          throw new Error(
+            `telegram sendMessage failed: ${redactToken(resp.description ?? "unknown")}`,
+          );
+        }
+        if (resp.result?.message_id !== undefined) {
+          lastMessageId = `telegram:${chatId}:${resp.result.message_id}`;
+        }
+      }
+      const sendAt = Date.now();
+      statusSnapshot = { ...statusSnapshot, lastSendAt: sendAt };
+      // W11: push to the gateway snapshot too — the dashboard reads this.
+      if (liveSetStatus) liveSetStatus({ lastSendAt: sendAt });
+      return { providerMessageId: lastMessageId };
+    },
+
+    async typing(ctx: ChannelTypingContext): Promise<void> {
+      if (!loadTokenFromSecretIfNeeded()) return;
+      const chatId = chatIdFromConversation(ctx.conversationId);
+      if (!chatId) return;
+      try {
+        await callApi("sendChatAction", { chat_id: chatId, action: "typing" }, 10_000);
+      } catch (err) {
+        ctx.log.warn("telegram typing failed", { err: redactToken(String(err)) });
+      }
+    },
+
+    status(): ChannelStatusSnapshot {
+      return { ...statusSnapshot };
+    },
+  };
+
+  return adapter;
+}
+
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    if (signal?.aborted) {
+      resolve();
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      resolve();
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+

package/src/gateway/channels/text-split.ts

@@ -0,0 +1,29 @@
+/**
+ * Split a long message into chunks <= `limit` characters each. Prefers to cut
+ * on newline boundaries so multi-paragraph replies don't fragment mid-line.
+ *
+ * Shared by third-party channel adapters (Telegram, WeChat) which both have a
+ * per-message size cap from upstream and no native streaming. WeChat caller
+ * passes a smaller `limit` (~1800), Telegram a larger one (~4000, since the
+ * raw Telegram limit is 4096).
+ *
+ * Empty input returns `[""]` so callers can iterate uniformly without a length
+ * check.
+ */
+export function splitText(text: string, limit: number): string[] {
+  if (limit <= 0) return [text];
+  if (text.length === 0) return [""];
+  if (text.length <= limit) return [text];
+
+  const out: string[] = [];
+  let remaining = text;
+  while (remaining.length > limit) {
+    let cut = remaining.lastIndexOf("\n", limit);
+    if (cut <= 0) cut = limit;
+    out.push(remaining.slice(0, cut));
+    // Drop the leading newline so the next chunk doesn't start with a blank line.
+    remaining = remaining.slice(cut).replace(/^\n/, "");
+  }
+  if (remaining.length > 0) out.push(remaining);
+  return out;
+}

package/src/gateway/channels/url-guard.ts

@@ -0,0 +1,55 @@
+/**
+ * W9: SSRF guard for user-supplied `baseUrl` values that flow into
+ * authenticated daemon-side fetches (Telegram getMe, WeChat iLink).
+ *
+ * Policy: scheme MUST be `https`; the hostname MUST match one of the
+ * explicitly-allowed well-known API hosts (case-insensitive exact match).
+ * Switching from blocklist to allowlist closes the GCP/AWS metadata hostname
+ * pivot vector — blocklists miss names like `metadata.google.internal`,
+ * `*.svc.cluster.local`, etc.
+ *
+ * The test host `botcord-test.local` is added only when
+ * NODE_ENV === "test" to keep unit tests working without relaxing production
+ * policy.
+ */
+
+export class UnsafeBaseUrlError extends Error {
+  constructor(reason: string) {
+    super(`unsafe_base_url: ${reason}`);
+    this.name = "UnsafeBaseUrlError";
+  }
+}
+
+function allowedHosts(): Set<string> {
+  const hosts = new Set(["api.telegram.org", "ilinkai.weixin.qq.com"]);
+  if (process.env.NODE_ENV === "test") {
+    hosts.add("botcord-test.local");
+  }
+  return hosts;
+}
+
+export function assertSafeBaseUrl(value: string | undefined | null): void {
+  if (value === undefined || value === null || value === "") {
+    // Caller handles the "no baseUrl supplied → use default" path.
+    return;
+  }
+  if (typeof value !== "string") {
+    throw new UnsafeBaseUrlError("not a string");
+  }
+  let parsed: URL;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw new UnsafeBaseUrlError("not a valid URL");
+  }
+  if (parsed.protocol !== "https:") {
+    throw new UnsafeBaseUrlError(`scheme "${parsed.protocol}" is not https`);
+  }
+  const host = parsed.hostname.toLowerCase();
+  if (!host) {
+    throw new UnsafeBaseUrlError("empty host");
+  }
+  if (!allowedHosts().has(host)) {
+    throw new UnsafeBaseUrlError(`host "${host}" is not in the allowlist`);
+  }
+}

package/src/gateway/channels/wechat-http.ts

@@ -0,0 +1,35 @@
+/**
+ * Shared HTTP plumbing for the iLink WeChat adapter and its login helper.
+ *
+ * Centralises the four mandatory headers (`AuthorizationType`,
+ * `Authorization`, `X-WECHAT-UIN`, `Content-Type`) so the adapter and the
+ * login flow can't drift on header shape — the iLink server rejects requests
+ * that omit any of them.
+ */
+
+import { randomBytes } from "node:crypto";
+
+// W7: canonical FetchLike now lives in http-types.ts; re-export for callers
+// that historically imported it from this module.
+export type { FetchLike } from "./http-types.js";
+
+/** `X-WECHAT-UIN: base64(str(random uint32))` — fresh per request, anti-replay. */
+export function wechatUinHeader(): string {
+  const n = randomBytes(4).readUInt32BE(0);
+  return Buffer.from(String(n), "utf8").toString("base64");
+}
+
+/** Build the canonical iLink request headers. Token is optional for login calls. */
+export function wechatHeaders(botToken?: string): Record<string, string> {
+  const h: Record<string, string> = {
+    "Content-Type": "application/json",
+    AuthorizationType: "ilink_bot_token",
+    "X-WECHAT-UIN": wechatUinHeader(),
+  };
+  if (botToken) h["Authorization"] = `Bearer ${botToken}`;
+  return h;
+}
+
+/** iLink `base_info` block required on every authenticated POST body. */
+export const WECHAT_CHANNEL_VERSION = "1.0.2";
+export const WECHAT_BASE_INFO = { channel_version: WECHAT_CHANNEL_VERSION } as const;

package/src/gateway/channels/wechat-login.ts

@@ -0,0 +1,90 @@
+/**
+ * iLink WeChat QR-code login helpers.
+ *
+ * Co-located with the channel adapter so the small set of unauthenticated
+ * iLink endpoints (`get_bot_qrcode`, `get_qrcode_status`) used during the
+ * scan-confirm flow stay alongside the authenticated calls in `wechat.ts`.
+ *
+ * This module deliberately exports ONLY the two HTTP calls. Login session
+ * persistence (mapping `loginId` → `{accountId, gatewayId, botToken, ...}`)
+ * is owned by the control-plane layer and is out of scope here.
+ */
+
+import { wechatHeaders, type FetchLike } from "./wechat-http.js";
+import { assertSafeBaseUrl } from "./url-guard.js";
+
+export const DEFAULT_WECHAT_BASE_URL = "https://ilinkai.weixin.qq.com";
+
+export interface WechatQrcode {
+  qrcode: string;
+  qrcodeUrl?: string;
+  raw: Record<string, unknown>;
+}
+
+export interface WechatQrcodeStatus {
+  status: string;
+  botToken?: string;
+  baseUrl?: string;
+  raw: Record<string, unknown>;
+}
+
+export interface WechatLoginOptions {
+  baseUrl?: string;
+  fetchImpl?: FetchLike;
+}
+
+/** `GET /ilink/bot/get_bot_qrcode?bot_type=3` — fetch a fresh login QR. */
+export async function getBotQrcode(opts: WechatLoginOptions = {}): Promise<WechatQrcode> {
+  // W1: defense-in-depth SSRF guard at the fetch boundary.
+  assertSafeBaseUrl(opts.baseUrl);
+  const base = (opts.baseUrl ?? DEFAULT_WECHAT_BASE_URL).replace(/\/+$/, "");
+  const fetcher = opts.fetchImpl ?? (globalThis.fetch as FetchLike);
+  const res = await fetcher(`${base}/ilink/bot/get_bot_qrcode?bot_type=3`, {
+    method: "GET",
+    headers: wechatHeaders(),
+  });
+  const data = (await safeJson(res)) ?? {};
+  const qrcode = typeof data.qrcode === "string" ? data.qrcode : "";
+  if (!qrcode) {
+    throw new Error(`wechat get_bot_qrcode: missing qrcode in response`);
+  }
+  const qrcodeUrl =
+    (typeof data.qrcode_url === "string" && data.qrcode_url) ||
+    (typeof data.qrcode_img_content === "string" && data.qrcode_img_content) ||
+    undefined;
+  return { qrcode, qrcodeUrl, raw: data };
+}
+
+/**
+ * `GET /ilink/bot/get_qrcode_status?qrcode=...` — poll for scan/confirm.
+ * Caller is responsible for backoff and TTL; this just returns the parsed
+ * server response.
+ */
+export async function getQrcodeStatus(
+  qrcode: string,
+  opts: WechatLoginOptions = {},
+): Promise<WechatQrcodeStatus> {
+  // W1: defense-in-depth SSRF guard at the fetch boundary.
+  assertSafeBaseUrl(opts.baseUrl);
+  const base = (opts.baseUrl ?? DEFAULT_WECHAT_BASE_URL).replace(/\/+$/, "");
+  const fetcher = opts.fetchImpl ?? (globalThis.fetch as FetchLike);
+  const res = await fetcher(
+    `${base}/ilink/bot/get_qrcode_status?qrcode=${encodeURIComponent(qrcode)}`,
+    { method: "GET", headers: wechatHeaders() },
+  );
+  const data = (await safeJson(res)) ?? {};
+  const status = typeof data.status === "string" ? data.status : "unknown";
+  const botToken = typeof data.bot_token === "string" ? data.bot_token : undefined;
+  const baseUrl = typeof data.baseurl === "string" ? data.baseurl : undefined;
+  return { status, botToken, baseUrl, raw: data };
+}
+
+async function safeJson(res: { text(): Promise<string> }): Promise<Record<string, unknown> | null> {
+  try {
+    const raw = await res.text();
+    if (!raw) return null;
+    return JSON.parse(raw) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}