@openclaw/qqbot 2026.5.1-beta.1

package/src/engine/group/message-gating.test.ts

@@ -0,0 +1,188 @@
+import { describe, expect, it } from "vitest";
+import {
+  resolveGroupMessageGate,
+  type GroupMessageGateInput,
+  type GroupMessageGateResult,
+} from "./message-gating.js";
+
+// Compose a full input so each test can override just the interesting axis.
+function input(overrides: Partial<GroupMessageGateInput>): GroupMessageGateInput {
+  return {
+    ignoreOtherMentions: false,
+    hasAnyMention: false,
+    wasMentioned: false,
+    implicitMention: false,
+    allowTextCommands: true,
+    isControlCommand: false,
+    commandAuthorized: false,
+    requireMention: true,
+    canDetectMention: true,
+    ...overrides,
+  };
+}
+
+function expectAction(
+  result: GroupMessageGateResult,
+  action: GroupMessageGateResult["action"],
+): void {
+  expect(result.action).toBe(action);
+}
+
+describe("engine/group/message-gating", () => {
+  describe("Layer 1: ignoreOtherMentions", () => {
+    it("drops messages that @other users when enabled", () => {
+      const result = resolveGroupMessageGate(
+        input({ ignoreOtherMentions: true, hasAnyMention: true }),
+      );
+      expectAction(result, "drop_other_mention");
+    });
+
+    it("does NOT drop when the bot itself was @-ed", () => {
+      const result = resolveGroupMessageGate(
+        input({ ignoreOtherMentions: true, hasAnyMention: true, wasMentioned: true }),
+      );
+      expectAction(result, "pass");
+    });
+
+    it("does NOT drop when implicitly mentioned via quote", () => {
+      const result = resolveGroupMessageGate(
+        input({ ignoreOtherMentions: true, hasAnyMention: true, implicitMention: true }),
+      );
+      expectAction(result, "pass");
+    });
+
+    it("is inactive when ignoreOtherMentions is off", () => {
+      const result = resolveGroupMessageGate(
+        input({ ignoreOtherMentions: false, hasAnyMention: true }),
+      );
+      // Falls through to mention gate — requireMention on, so skipped.
+      expectAction(result, "skip_no_mention");
+    });
+  });
+
+  describe("Layer 2: unauthorized control command", () => {
+    it("silently blocks an unauthorized /stop", () => {
+      const result = resolveGroupMessageGate(
+        input({ isControlCommand: true, commandAuthorized: false }),
+      );
+      expectAction(result, "block_unauthorized_command");
+    });
+
+    it("passes through when sender is authorized", () => {
+      const result = resolveGroupMessageGate(
+        input({ isControlCommand: true, commandAuthorized: true, wasMentioned: true }),
+      );
+      expectAction(result, "pass");
+    });
+
+    it("does not trigger when text commands are disabled", () => {
+      const result = resolveGroupMessageGate(
+        input({
+          allowTextCommands: false,
+          isControlCommand: true,
+          commandAuthorized: false,
+          wasMentioned: true,
+        }),
+      );
+      // allowTextCommands=false skips the block, so the mention gate decides.
+      expectAction(result, "pass");
+    });
+  });
+
+  describe("Layer 3: mention gating", () => {
+    it("requires @bot when requireMention is on", () => {
+      const result = resolveGroupMessageGate(input({ requireMention: true }));
+      expectAction(result, "skip_no_mention");
+      expect(result.effectiveWasMentioned).toBe(false);
+    });
+
+    it("passes through when explicitly mentioned", () => {
+      const result = resolveGroupMessageGate(input({ requireMention: true, wasMentioned: true }));
+      expectAction(result, "pass");
+      expect(result.effectiveWasMentioned).toBe(true);
+    });
+
+    it("passes through on implicit mention", () => {
+      const result = resolveGroupMessageGate(
+        input({ requireMention: true, implicitMention: true }),
+      );
+      expectAction(result, "pass");
+      expect(result.effectiveWasMentioned).toBe(true);
+    });
+
+    it("passes through when requireMention is off", () => {
+      const result = resolveGroupMessageGate(input({ requireMention: false }));
+      expectAction(result, "pass");
+    });
+
+    it("passes through when mention cannot be detected (DMs)", () => {
+      const result = resolveGroupMessageGate(
+        input({ requireMention: true, canDetectMention: false }),
+      );
+      expectAction(result, "pass");
+    });
+  });
+
+  describe("command bypass", () => {
+    it("bypasses mention gate for an authorized control command", () => {
+      const result = resolveGroupMessageGate(
+        input({
+          requireMention: true,
+          isControlCommand: true,
+          commandAuthorized: true,
+          allowTextCommands: true,
+        }),
+      );
+      expectAction(result, "pass");
+      expect(result.shouldBypassMention).toBe(true);
+      expect(result.effectiveWasMentioned).toBe(true);
+    });
+
+    it("does NOT bypass when the command @-s another user", () => {
+      const result = resolveGroupMessageGate(
+        input({
+          requireMention: true,
+          isControlCommand: true,
+          commandAuthorized: true,
+          hasAnyMention: true,
+        }),
+      );
+      expectAction(result, "skip_no_mention");
+      expect(result.shouldBypassMention).toBe(false);
+    });
+
+    it("is a no-op when requireMention is off", () => {
+      const result = resolveGroupMessageGate(
+        input({
+          requireMention: false,
+          isControlCommand: true,
+          commandAuthorized: true,
+        }),
+      );
+      expectAction(result, "pass");
+      // requireMention=false means bypass is unnecessary (condition 1 fails).
+      expect(result.shouldBypassMention).toBe(false);
+    });
+  });
+
+  describe("priority ordering", () => {
+    it("layer 1 wins over layer 2 (ignoreOtherMentions before block)", () => {
+      const result = resolveGroupMessageGate(
+        input({
+          ignoreOtherMentions: true,
+          hasAnyMention: true,
+          isControlCommand: true,
+          commandAuthorized: false,
+        }),
+      );
+      expectAction(result, "drop_other_mention");
+    });
+
+    it("layer 2 wins over layer 3 (unauthorized command before skip)", () => {
+      const result = resolveGroupMessageGate(
+        input({ requireMention: true, isControlCommand: true, commandAuthorized: false }),
+      );
+      expectAction(result, "block_unauthorized_command");
+    });
+  });
+});

package/src/engine/group/message-gating.ts

@@ -0,0 +1,216 @@
+/**
+ * Group message gate — unified entry point for group inbound gating.
+ *
+ * Collapses three orthogonal rules that previously lived in ad-hoc spots
+ * of the standalone gateway into a single pure function. Callers pass in
+ * the message's mention state plus the resolved configuration, and get
+ * back a structured action telling them how to handle the message.
+ *
+ * Evaluation order (short-circuit at the first match):
+ *   1. `ignoreOtherMentions` — message @-s someone else but not the bot
+ *                              → `drop_other_mention` (record to history,
+ *                              then drop). Implicit mentions (e.g. quoting
+ *                              a bot reply) still count as @bot.
+ *   2. `block_unauthorized_command` — sender is not allowed to run control
+ *                                     commands (text starts with `/xxx`)
+ *                                     → silently drop.
+ *   3. `mention gating` — when `requireMention` is on, non-@bot messages
+ *                         are `skip_no_mention`'d (still buffered to
+ *                         history). Authorized control commands can
+ *                         **bypass** the gate as long as the message does
+ *                         not @anyone else at the same time.
+ *   4. Otherwise → `pass` (the message will reach the AI pipeline).
+ *
+ * All inputs are plain data; there is no I/O and no mutation, so the
+ * function is safe to share between the built-in and standalone builds.
+ */
+
+// ────────────────────── Types ──────────────────────
+
+/**
+ * Structured action returned by {@link resolveGroupMessageGate}.
+ *
+ * - `drop_other_mention`        — message @-s another user but not the bot;
+ *                                 record to the group history cache and
+ *                                 drop without hitting the AI.
+ * - `block_unauthorized_command` — silently refuse a control command from
+ *                                  an unauthorized sender (no history
+ *                                  write, no AI call).
+ * - `skip_no_mention`           — `requireMention` is on and the message
+ *                                 does not @bot; record to history but
+ *                                 skip AI dispatch.
+ * - `pass`                      — forward the message to the AI pipeline.
+ */
+type GroupMessageGateAction =
+  | "drop_other_mention"
+  | "block_unauthorized_command"
+  | "skip_no_mention"
+  | "pass";
+
+/** Gate evaluation result. */
+export interface GroupMessageGateResult {
+  /** The action the caller should take. */
+  action: GroupMessageGateAction;
+  /**
+   * Effective mention state after combining raw mention detection with
+   * implicit / bypass signals. Only meaningful when `action === "pass"`.
+   */
+  effectiveWasMentioned: boolean;
+  /**
+   * Whether the control-command bypass was applied to flip a missing
+   * mention into `pass`. Only meaningful when `action === "pass"`.
+   */
+  shouldBypassMention: boolean;
+}
+
+/** Input for {@link resolveGroupMessageGate}. */
+export interface GroupMessageGateInput {
+  // ---- ignoreOtherMentions layer ----
+  /** Per-group config: drop messages that @someone other than the bot. */
+  ignoreOtherMentions: boolean;
+  /** Whether the message contains *any* @mention (including @other-user). */
+  hasAnyMention: boolean;
+  /**
+   * Whether the QQ event explicitly @-s the bot (via `mentions[].is_you`
+   * or `GROUP_AT_MESSAGE_CREATE`).
+   */
+  wasMentioned: boolean;
+  /**
+   * Implicit mention — e.g. the message quotes an earlier bot reply.
+   * Treated as equivalent to an explicit @bot for gating purposes.
+   */
+  implicitMention: boolean;
+
+  // ---- Control-command layer ----
+  /** Whether text-based control commands are enabled globally. */
+  allowTextCommands: boolean;
+  /** Whether the current message is recognised as a control command. */
+  isControlCommand: boolean;
+  /** Whether the sender is authorised to run control commands. */
+  commandAuthorized: boolean;
+
+  // ---- Mention gating layer ----
+  /** Per-group config: `requireMention` — bot only replies when @-ed. */
+  requireMention: boolean;
+  /**
+   * Whether the channel can reliably detect @-mentions at all. In C2C chat
+   * this should be `false` (DMs don't have mentions); in group chat it
+   * should be `true`.
+   */
+  canDetectMention: boolean;
+}
+
+// ────────────────────── Core logic ──────────────────────
+
+/**
+ * Base mention-gate evaluation.
+ *
+ * `effectiveWasMentioned = wasMentioned || implicitMention || bypass`.
+ * `shouldSkip = requireMention && canDetectMention && !effectiveWasMentioned`.
+ */
+function resolveMentionGating(input: {
+  requireMention: boolean;
+  canDetectMention: boolean;
+  wasMentioned: boolean;
+  implicitMention: boolean;
+  shouldBypassMention: boolean;
+}): { effectiveWasMentioned: boolean; shouldSkip: boolean } {
+  const effectiveWasMentioned =
+    input.wasMentioned || input.implicitMention || input.shouldBypassMention;
+  const shouldSkip = input.requireMention && input.canDetectMention && !effectiveWasMentioned;
+  return { effectiveWasMentioned, shouldSkip };
+}
+
+/**
+ * Decide whether an authorized control command may bypass the mention gate.
+ *
+ * All of the following must hold:
+ *   1. `requireMention` is on         (gate is active)
+ *   2. The bot was NOT directly @-ed  (otherwise no bypass is needed)
+ *   3. The message does NOT @anyone   (a `@other-user /stop` should NOT pass
+ *                                      — the command wasn't aimed at us)
+ *   4. Text commands are enabled
+ *   5. Sender is authorised
+ *   6. The content is a valid control command
+ */
+function resolveCommandBypass(input: {
+  requireMention: boolean;
+  wasMentioned: boolean;
+  hasAnyMention: boolean;
+  allowTextCommands: boolean;
+  commandAuthorized: boolean;
+  isControlCommand: boolean;
+}): boolean {
+  return (
+    input.requireMention &&
+    !input.wasMentioned &&
+    !input.hasAnyMention &&
+    input.allowTextCommands &&
+    input.commandAuthorized &&
+    input.isControlCommand
+  );
+}
+
+// ────────────────────── Unified gate ──────────────────────
+
+/**
+ * Evaluate the group-message gate.
+ *
+ * See the module-level docs for the ordering and semantics.
+ */
+export function resolveGroupMessageGate(input: GroupMessageGateInput): GroupMessageGateResult {
+  // ---- Layer 1: ignoreOtherMentions ----
+  if (
+    input.ignoreOtherMentions &&
+    input.hasAnyMention &&
+    !input.wasMentioned &&
+    !input.implicitMention
+  ) {
+    return {
+      action: "drop_other_mention",
+      effectiveWasMentioned: false,
+      shouldBypassMention: false,
+    };
+  }
+
+  // ---- Layer 2: unauthorized control command ----
+  if (input.allowTextCommands && input.isControlCommand && !input.commandAuthorized) {
+    return {
+      action: "block_unauthorized_command",
+      effectiveWasMentioned: false,
+      shouldBypassMention: false,
+    };
+  }
+
+  // ---- Layer 3: mention gate + command bypass ----
+  const shouldBypassMention = resolveCommandBypass({
+    requireMention: input.requireMention,
+    wasMentioned: input.wasMentioned,
+    hasAnyMention: input.hasAnyMention,
+    allowTextCommands: input.allowTextCommands,
+    commandAuthorized: input.commandAuthorized,
+    isControlCommand: input.isControlCommand,
+  });
+
+  const mentionGate = resolveMentionGating({
+    requireMention: input.requireMention,
+    canDetectMention: input.canDetectMention,
+    wasMentioned: input.wasMentioned,
+    implicitMention: input.implicitMention,
+    shouldBypassMention,
+  });
+
+  if (mentionGate.shouldSkip) {
+    return {
+      action: "skip_no_mention",
+      effectiveWasMentioned: mentionGate.effectiveWasMentioned,
+      shouldBypassMention,
+    };
+  }
+
+  return {
+    action: "pass",
+    effectiveWasMentioned: mentionGate.effectiveWasMentioned,
+    shouldBypassMention,
+  };
+}

package/src/engine/messaging/decode-media-path.ts

@@ -0,0 +1,82 @@
+/**
+ * Media path decoding utility.
+ *
+ * Extracted from `outbound-deliver.ts` — handles the `MEDIA:` prefix stripping,
+ * tilde expansion, octal escape / UTF-8 byte-sequence decoding, and backslash
+ * unescaping that media tags require.
+ *
+ * Zero external dependencies.
+ */
+
+import type { EngineLogger } from "../types.js";
+
+/**
+ * Normalize a file path by expanding `~` to the home directory and trimming.
+ *
+ * This is a minimal re-implementation of `utils/platform.ts#normalizePath`
+ * so that `core/` remains self-contained.
+ */
+function normalizePath(p: string): string {
+  let result = p.trim();
+  if (result.startsWith("~/") || result === "~") {
+    const home =
+      typeof process !== "undefined" ? (process.env.HOME ?? process.env.USERPROFILE) : undefined;
+    if (home) {
+      result = result === "~" ? home : `${home}${result.slice(1)}`;
+    }
+  }
+  return result;
+}
+
+/**
+ * Decode a media path by stripping `MEDIA:`, expanding `~`, and unescaping
+ * octal/UTF-8 byte sequences.
+ *
+ * @param raw - Raw path string from a media tag.
+ * @param log - Optional logger for decode diagnostics.
+ * @returns The decoded, normalized media path.
+ */
+export function decodeMediaPath(raw: string, log?: EngineLogger): string {
+  let mediaPath = raw;
+  if (mediaPath.startsWith("MEDIA:")) {
+    mediaPath = mediaPath.slice("MEDIA:".length);
+  }
+  mediaPath = normalizePath(mediaPath);
+  mediaPath = mediaPath.replace(/\\\\/g, "\\");
+
+  // Skip octal escape decoding for Windows local paths (e.g. C:\Users\1\file.txt)
+  // where backslash-digit sequences like \1, \2 ... \7 are directory separators,
+  // not octal escape sequences.
+  const isWinLocal = /^[a-zA-Z]:[\\/]/.test(mediaPath) || mediaPath.startsWith("\\\\");
+  try {
+    const hasOctal = /\\[0-7]{1,3}/.test(mediaPath);
+    const hasNonASCII = /[\u0080-\u00FF]/.test(mediaPath);
+
+    if (!isWinLocal && (hasOctal || hasNonASCII)) {
+      log?.debug?.(`Decoding path with mixed encoding: ${mediaPath}`);
+      const decoded = mediaPath.replace(/\\([0-7]{1,3})/g, (_: string, octal: string) => {
+        return String.fromCharCode(Number.parseInt(octal, 8));
+      });
+      const bytes: number[] = [];
+      for (let i = 0; i < decoded.length; i++) {
+        const code = decoded.charCodeAt(i);
+        if (code <= 0xff) {
+          bytes.push(code);
+        } else {
+          const charBytes = Buffer.from(decoded[i], "utf8");
+          bytes.push(...charBytes);
+        }
+      }
+      const buffer = Buffer.from(bytes);
+      const utf8Decoded = buffer.toString("utf8");
+      if (!utf8Decoded.includes("\uFFFD") || utf8Decoded.length < decoded.length) {
+        mediaPath = utf8Decoded;
+        log?.debug?.(`Successfully decoded path: ${mediaPath}`);
+      }
+    }
+  } catch (decodeErr) {
+    log?.error(`Path decode error: ${String(decodeErr)}`);
+  }
+
+  return mediaPath;
+}

package/src/engine/messaging/media-source.ts

@@ -0,0 +1,215 @@
+/**
+ * Unified media-source abstraction for the QQ Bot upload pipeline.
+ *
+ * All rich-media entry points (sender.ts#sendMedia, outbound.ts#send*,
+ * reply-dispatcher.ts#handle*Payload) funnel through {@link normalizeSource}
+ * before reaching the low-level {@link MediaApi}.
+ *
+ * ## Why four branches?
+ *
+ * - `url` — remote http(s) URL that the QQ server can fetch directly.
+ * - `base64` — in-memory base64 string (typically from a `data:` URL).
+ * - `localPath` — on-disk file; kept as a path so a future chunked-upload
+ *   implementation can stream it via `fs.createReadStream` without the 4/3×
+ *   base64 memory overhead.
+ * - `buffer` — in-memory raw bytes (e.g. TTS output, downloaded url-fallback).
+ *
+ * ## Security baseline (localPath branch)
+ *
+ * `openLocalFile` is the single canonical implementation of "safely open a
+ * local file for upload" across the plugin. It merges the previously
+ * inconsistent strategies from `reply-dispatcher.ts` (O_NOFOLLOW + size check)
+ * and `outbound.ts` (realpath + root containment). Callers are still
+ * responsible for *root-whitelist* validation (via
+ * `resolveQQBotPayloadLocalFilePath` / `resolveOutboundMediaPath`) before
+ * passing the path in; this function enforces *file-level* safety only.
+ *
+ * Chunked upload is not implemented in this PR, but the contract here already
+ * returns `size` metadata so `sendMediaInternal` can route by size without
+ * reading the whole file first.
+ */
+
+import * as fs from "node:fs";
+import { MAX_UPLOAD_SIZE, formatFileSize, getMimeType } from "../utils/file-utils.js";
+
+// ============ Types ============
+
+/**
+ * Fully normalized media source. Downstream uploaders switch on `kind`.
+ *
+ * - `url`: remote URL — upload via `file_data=null; url=...`.
+ * - `base64`: already-encoded base64 — upload via `file_data=...`.
+ * - `localPath`: on-disk file — one-shot path reads it into a buffer;
+ *   chunked path (future) streams it via `fs.createReadStream`.
+ * - `buffer`: raw bytes in memory — same as above minus disk I/O.
+ */
+export type MediaSource =
+  | { kind: "url"; url: string }
+  | { kind: "base64"; data: string; mime?: string }
+  | { kind: "localPath"; path: string; size: number; mime?: string }
+  | { kind: "buffer"; buffer: Buffer; fileName?: string; mime?: string };
+
+/**
+ * Untyped media source accepted from callers.
+ *
+ * `url` may be either a remote `http(s)://...` URL or a `data:<mime>;base64,...`
+ * data URL — {@link normalizeSource} transparently resolves the latter to a
+ * `base64` branch.
+ */
+export type RawMediaSource =
+  | { url: string }
+  | { base64: string; mime?: string }
+  | { localPath: string }
+  | { buffer: Buffer; fileName?: string; mime?: string };
+
+// ============ data: URL ============
+
+const DATA_URL_RE = /^data:([^;,]+);base64,(.+)$/i;
+
+/**
+ * Parse a `data:<mime>;base64,<payload>` URL.
+ *
+ * Returns `null` when the string is not a data URL or does not declare
+ * base64 encoding. Non-base64 data URLs are intentionally rejected because
+ * the QQ upload API ingests raw base64, not arbitrary URL-encoded payloads.
+ */
+function tryParseDataUrl(value: string): { mime: string; data: string } | null {
+  if (!value.startsWith("data:")) {
+    return null;
+  }
+  const m = value.match(DATA_URL_RE);
+  if (!m) {
+    return null;
+  }
+  return { mime: m[1], data: m[2] };
+}
+
+// ============ Local file safe open ============
+
+/**
+ * Opened handle to a local file, with metadata already validated against
+ * QQ upload limits.
+ *
+ * Callers MUST call {@link OpenedLocalFile.close} (typically in a `finally`).
+ */
+interface OpenedLocalFile {
+  handle: fs.promises.FileHandle;
+  size: number;
+  close(): Promise<void>;
+}
+
+/**
+ * Open a local file for upload with defense-in-depth:
+ *
+ * 1. `O_NOFOLLOW` refuses to traverse symlinks (prevents post-whitelist
+ *    symlink swaps / TOCTOU attacks).
+ * 2. `fstat` on the opened descriptor — NOT `fs.stat` on the path —
+ *    so the size check applies to the exact byte stream we will read.
+ * 3. Rejects non-regular files (sockets / devices / directories).
+ * 4. Enforces a caller-specified `maxSize` (default {@link MAX_UPLOAD_SIZE})
+ *    at open time, so oversized files fail fast without allocating a
+ *    full buffer. Chunked upload callers should pass a larger ceiling
+ *    (e.g. `CHUNKED_UPLOAD_MAX_SIZE` from `utils/file-utils.js`).
+ *
+ * The caller receives the open handle plus validated size and is expected
+ * to either {@link OpenedLocalFile.handle.readFile} (one-shot path) or
+ * stream via `fs.createReadStream` (chunked path).
+ */
+export async function openLocalFile(
+  filePath: string,
+  opts: { maxSize?: number } = {},
+): Promise<OpenedLocalFile> {
+  const maxSize = opts.maxSize ?? MAX_UPLOAD_SIZE;
+  const openFlags =
+    fs.constants.O_RDONLY | ("O_NOFOLLOW" in fs.constants ? fs.constants.O_NOFOLLOW : 0);
+  const handle = await fs.promises.open(filePath, openFlags);
+  try {
+    const stat = await handle.stat();
+    if (!stat.isFile()) {
+      throw new Error("Path is not a regular file");
+    }
+    if (stat.size > maxSize) {
+      throw new Error(
+        `File is too large (${formatFileSize(stat.size)}); QQ Bot API limit is ${formatFileSize(maxSize)}`,
+      );
+    }
+    return {
+      handle,
+      size: stat.size,
+      close: () => handle.close(),
+    };
+  } catch (err) {
+    // Close the handle on any validation failure to avoid fd leaks.
+    await handle.close().catch(() => undefined);
+    throw err;
+  }
+}
+
+// ============ Normalization ============
+
+/**
+ * Normalize a {@link RawMediaSource} into a {@link MediaSource}.
+ *
+ * - Strings passed via `{ url }` that start with `data:` are auto-resolved
+ *   to a `base64` branch (this is the unified `data:` URL support that was
+ *   previously only implemented in `sendImage`).
+ * - `localPath` branches open the file with {@link openLocalFile} solely to
+ *   validate size / regular-file / O_NOFOLLOW invariants. The handle is
+ *   closed immediately — actual reading is deferred to the uploader so
+ *   the chunked path can stream without double-reading.
+ * - `buffer` branches enforce the same ceiling inline.
+ *
+ * `maxSize` defaults to {@link MAX_UPLOAD_SIZE} (20MB, one-shot upload limit).
+ * Callers that dispatch to the chunked uploader should pass a larger ceiling
+ * (e.g. `CHUNKED_UPLOAD_MAX_SIZE`, or a value derived from
+ * `getMaxUploadSize(fileType)`).
+ *
+ * NOTE: Root-whitelist validation (i.e. "this path must live under the
+ * allowed QQ Bot media directory") is a caller concern. This function
+ * assumes the path has already passed such checks.
+ */
+export async function normalizeSource(
+  raw: RawMediaSource,
+  opts: { maxSize?: number } = {},
+): Promise<MediaSource> {
+  const maxSize = opts.maxSize ?? MAX_UPLOAD_SIZE;
+
+  if ("url" in raw) {
+    const parsed = tryParseDataUrl(raw.url);
+    if (parsed) {
+      return { kind: "base64", data: parsed.data, mime: parsed.mime };
+    }
+    return { kind: "url", url: raw.url };
+  }
+
+  if ("base64" in raw) {
+    return { kind: "base64", data: raw.base64, mime: raw.mime };
+  }
+
+  if ("localPath" in raw) {
+    const opened = await openLocalFile(raw.localPath, { maxSize });
+    try {
+      return {
+        kind: "localPath",
+        path: raw.localPath,
+        size: opened.size,
+        mime: getMimeType(raw.localPath),
+      };
+    } finally {
+      await opened.close();
+    }
+  }
+
+  // buffer branch
+  if (raw.buffer.length > maxSize) {
+    throw new Error(
+      `Buffer is too large (${formatFileSize(raw.buffer.length)}); QQ Bot API limit is ${formatFileSize(maxSize)}`,
+    );
+  }
+  return {
+    kind: "buffer",
+    buffer: raw.buffer,
+    fileName: raw.fileName,
+    mime: raw.mime,
+  };
+}