@soimy/dingtalk 3.6.11 → 3.7.0

package/src/{media-utils.ts → messaging/media-utils.ts}

@@ -1,4 +1,4 @@
-// src/media-utils.ts
+// src/messaging/media-utils.ts
 
 /**
  * Media handling utilities for DingTalk channel plugin.
@@ -6,17 +6,17 @@
  */
 
 import { randomUUID } from "node:crypto";
-import * as os from "node:os";
-import * as path from "node:path";
-import { promises as fsPromises } from "node:fs";
 import { lookup as dnsLookup } from "node:dns/promises";
+import { constants as fsConstants, promises as fsPromises } from "node:fs";
 import { BlockList, isIP } from "node:net";
-import axios from "./http-client";
+import * as os from "node:os";
+import * as path from "node:path";
 import FormData from "form-data";
 import { runFfmpeg, runFfprobe } from "openclaw/plugin-sdk/media-runtime";
-import type { DingTalkConfig, Logger } from "./types";
-import { formatDingTalkErrorPayloadLog, getProxyBypassOption } from "./utils";
-import { getDingTalkRuntime } from "./runtime";
+import { getDingTalkRuntime } from "../platform/runtime";
+import type { DingTalkConfig, Logger } from "../platform/types";
+import axios from "../shared/http-client";
+import { formatDingTalkErrorPayloadLog, getProxyBypassOption } from "../shared/utils";
 
 /**
  * Extended PluginRuntime with media bridge support.
@@ -40,11 +40,15 @@ interface PluginRuntimeWithMedia {
  * @param log Optional logger
  * @returns Duration in seconds (0 if parsing fails)
  */
-export async function getMp3DurationSeconds(filePathOrBuffer: string | Buffer, log?: Logger): Promise<number> {
+export async function getMp3DurationSeconds(
+  filePathOrBuffer: string | Buffer,
+  log?: Logger,
+): Promise<number> {
   try {
-    const buffer = typeof filePathOrBuffer === "string"
-      ? await fsPromises.readFile(filePathOrBuffer)
-      : filePathOrBuffer;
+    const buffer =
+      typeof filePathOrBuffer === "string"
+        ? await fsPromises.readFile(filePathOrBuffer)
+        : filePathOrBuffer;
     let offset = 0;
 
     // Skip ID3v2 tag if present
@@ -57,7 +61,7 @@ export async function getMp3DurationSeconds(filePathOrBuffer: string | Buffer, l
         (buffer[9] & 0x7f);
 
       // ID3 size excludes the 10-byte header; footer (if present) adds 10 bytes.
-      const footerSize = (flags & 0x10) ? 10 : 0;
+      const footerSize = flags & 0x10 ? 10 : 0;
       offset = 10 + id3Size + footerSize;
     }
 
@@ -100,7 +104,7 @@ export async function getMp3DurationSeconds(filePathOrBuffer: string | Buffer, l
       // Frame sync (11 bits set)
       if (buffer[offset] === 0xff && (buffer[offset + 1] & 0xe0) === 0xe0) {
         const versionBits = (buffer[offset + 1] >> 3) & 0x03; // 00=2.5, 01=reserved, 10=2, 11=1
-        const layerBits = (buffer[offset + 1] >> 1) & 0x03;   // 01=III, 10=II, 11=I, 00=reserved
+        const layerBits = (buffer[offset + 1] >> 1) & 0x03; // 01=III, 10=II, 11=I, 00=reserved
         const bitrateIndex = (buffer[offset + 2] >> 4) & 0x0f; // 0000/1111 invalid
         const sampleRateIndex = (buffer[offset + 2] >> 2) & 0x03; // 11 invalid
         const paddingBit = (buffer[offset + 2] >> 1) & 0x01;
@@ -199,10 +203,14 @@ export async function getMp3DurationSeconds(filePathOrBuffer: string | Buffer, l
       return Math.floor(duration);
     }
 
-    log?.warn?.(`[DingTalk] Could not parse MP3 duration from ${typeof filePathOrBuffer === "string" ? filePathOrBuffer : "<buffer>"} (found ${frameCount} frames)`);
+    log?.warn?.(
+      `[DingTalk] Could not parse MP3 duration from ${typeof filePathOrBuffer === "string" ? filePathOrBuffer : "<buffer>"} (found ${frameCount} frames)`,
+    );
     return 0;
   } catch (err: unknown) {
-    log?.error?.(`[DingTalk] Failed to get MP3 duration: ${err instanceof Error ? err.message : String(err)}`);
+    log?.error?.(
+      `[DingTalk] Failed to get MP3 duration: ${err instanceof Error ? err.message : String(err)}`,
+    );
     return 0;
   }
 }
@@ -211,6 +219,26 @@ const DEFAULT_VOICE_DURATION_MS = 1000;
 const DINGTALK_VOICE_UPLOAD_EXTENSIONS = new Set([".ogg", ".amr"]);
 const DINGTALK_VOICE_INPUT_EXTENSIONS = new Set([".ogg", ".amr", ".mp3", ".wav"]);
 
+/**
+ * Temp files this module created itself (remote media downloads and voice
+ * transcodes). They live outside `mediaLocalRoots` by design but are
+ * plugin-owned, so they may still be read directly instead of being rejected
+ * by the roots-gated runtime media bridge.
+ */
+const trustedHostMediaPaths = new Set<string>();
+
+function markTrustedHostMediaPath(filePath: string): void {
+  trustedHostMediaPaths.add(path.resolve(filePath));
+}
+
+function unmarkTrustedHostMediaPath(filePath: string): void {
+  trustedHostMediaPaths.delete(path.resolve(filePath));
+}
+
+function isTrustedHostMediaPath(filePath: string): boolean {
+  return trustedHostMediaPaths.has(path.resolve(filePath));
+}
+
 async function getDurationMsWithFfprobe(filePath: string, log?: Logger): Promise<number> {
   try {
     const stdout = await runFfprobe([
@@ -228,13 +256,16 @@ async function getDurationMsWithFfprobe(filePath: string, log?: Logger): Promise
     }
     return Math.max(1, Math.round(duration * 1000));
   } catch (err: unknown) {
-    log?.warn?.(`[DingTalk] Failed to probe voice duration: ${err instanceof Error ? err.message : String(err)}`);
+    log?.warn?.(
+      `[DingTalk] Failed to probe voice duration: ${err instanceof Error ? err.message : String(err)}`,
+    );
     return 0;
   }
 }
 
 async function prepareVoiceUploadPath(
   mediaPath: string,
+  options?: { mediaLocalRoots?: string[] },
   log?: Logger,
 ): Promise<{ path: string; cleanup?: () => Promise<void> }> {
   const ext = path.extname(mediaPath).toLowerCase();
@@ -242,30 +273,47 @@ async function prepareVoiceUploadPath(
     return { path: mediaPath };
   }
 
+  // ffmpeg must never open a caller path outside mediaLocalRoots, so stage the
+  // source through the roots-aware reader before transcoding.
+  const { buffer: sourceBuffer } = await readMediaBuffer(mediaPath, options, log);
+  const inputPath = path.join(os.tmpdir(), `dingtalk_voice_src_${randomUUID()}${ext}`);
+  await fsPromises.writeFile(inputPath, sourceBuffer);
+  markTrustedHostMediaPath(inputPath);
+
   const outputPath = path.join(os.tmpdir(), `dingtalk_voice_${randomUUID()}.ogg`);
-  await runFfmpeg([
-    "-y",
-    "-i",
-    mediaPath,
-    "-vn",
-    "-sn",
-    "-dn",
-    "-ar",
-    "16000",
-    "-ac",
-    "1",
-    "-c:a",
-    "libopus",
-    "-b:a",
-    "24k",
-    outputPath,
-  ]);
+  try {
+    await runFfmpeg([
+      "-y",
+      "-i",
+      inputPath,
+      "-vn",
+      "-sn",
+      "-dn",
+      "-ar",
+      "16000",
+      "-ac",
+      "1",
+      "-c:a",
+      "libopus",
+      "-b:a",
+      "24k",
+      outputPath,
+    ]);
+  } catch (err) {
+    await fsPromises.rm(outputPath, { force: true }).catch(() => {});
+    throw err;
+  } finally {
+    unmarkTrustedHostMediaPath(inputPath);
+    await fsPromises.rm(inputPath, { force: true }).catch(() => {});
+  }
 
   log?.debug?.(`[DingTalk] Transcoded voice upload to OGG: ${mediaPath} -> ${outputPath}`);
+  markTrustedHostMediaPath(outputPath);
 
   return {
     path: outputPath,
     cleanup: async () => {
+      unmarkTrustedHostMediaPath(outputPath);
       await fsPromises.rm(outputPath, { force: true });
     },
   };
@@ -273,7 +321,11 @@ async function prepareVoiceUploadPath(
 
 function getWavDurationMsFromBuffer(buffer: Buffer, log?: Logger): number {
   try {
-    if (buffer.length < 44 || buffer.toString("ascii", 0, 4) !== "RIFF" || buffer.toString("ascii", 8, 12) !== "WAVE") {
+    if (
+      buffer.length < 44 ||
+      buffer.toString("ascii", 0, 4) !== "RIFF" ||
+      buffer.toString("ascii", 8, 12) !== "WAVE"
+    ) {
       return 0;
     }
 
@@ -310,9 +362,11 @@ function getWavDurationMsFromBuffer(buffer: Buffer, log?: Logger): number {
       offset = chunkDataStart + paddedChunkSize;
     }
 
-    const effectiveByteRate = byteRate || (sampleRate > 0 && channels > 0 && bitsPerSample > 0
-      ? sampleRate * channels * (bitsPerSample / 8)
-      : 0);
+    const effectiveByteRate =
+      byteRate ||
+      (sampleRate > 0 && channels > 0 && bitsPerSample > 0
+        ? sampleRate * channels * (bitsPerSample / 8)
+        : 0);
 
     if (effectiveByteRate <= 0 || dataSize <= 0) {
       return 0;
@@ -320,7 +374,9 @@ function getWavDurationMsFromBuffer(buffer: Buffer, log?: Logger): number {
 
     return Math.max(1, Math.round((dataSize / effectiveByteRate) * 1000));
   } catch (err: unknown) {
-    log?.warn?.(`[DingTalk] Failed to parse WAV duration: ${err instanceof Error ? err.message : String(err)}`);
+    log?.warn?.(
+      `[DingTalk] Failed to parse WAV duration: ${err instanceof Error ? err.message : String(err)}`,
+    );
     return 0;
   }
 }
@@ -341,8 +397,8 @@ export async function getVoiceDurationMs(
     let durationSec: number;
     try {
       // Reuse pre-read buffer from uploadMedia when available to avoid double read
-      const buffer = options?.preReadBuffer
-        ?? (await readMediaBuffer(filePath, options, log)).buffer;
+      const buffer =
+        options?.preReadBuffer ?? (await readMediaBuffer(filePath, options, log)).buffer;
       durationSec = await getMp3DurationSeconds(buffer, log);
     } catch {
       durationSec = 0;
@@ -359,8 +415,8 @@ export async function getVoiceDurationMs(
 
   if (ext === ".wav") {
     try {
-      const buffer = options?.preReadBuffer
-        ?? (await readMediaBuffer(filePath, options, log)).buffer;
+      const buffer =
+        options?.preReadBuffer ?? (await readMediaBuffer(filePath, options, log)).buffer;
       const durationMs = getWavDurationMsFromBuffer(buffer, log);
       if (durationMs > 0) {
         return durationMs;
@@ -380,7 +436,6 @@ export async function getVoiceDurationMs(
   return DEFAULT_VOICE_DURATION_MS;
 }
 
-
 export type DingTalkMediaType = "image" | "voice" | "video" | "file";
 export type DingTalkOutboundMediaType = DingTalkMediaType;
 
@@ -503,7 +558,12 @@ function normalizeOutboundMediaType(value?: string | null): DingTalkOutboundMedi
   }
 
   const normalized = value.trim().toLowerCase();
-  if (normalized === "image" || normalized === "voice" || normalized === "video" || normalized === "file") {
+  if (
+    normalized === "image" ||
+    normalized === "voice" ||
+    normalized === "video" ||
+    normalized === "file"
+  ) {
     return normalized;
   }
 
@@ -523,7 +583,10 @@ export function resolveOutboundMediaType(params: {
       throw new Error('asVoice requires mediaType="voice" when mediaType is provided.');
     }
 
-    if (detectedType !== "voice" || !DINGTALK_VOICE_INPUT_EXTENSIONS.has(path.extname(params.mediaPath).toLowerCase())) {
+    if (
+      detectedType !== "voice" ||
+      !DINGTALK_VOICE_INPUT_EXTENSIONS.has(path.extname(params.mediaPath).toLowerCase())
+    ) {
       throw new Error("asVoice requires an audio file (ogg, amr, mp3, wav).");
     }
 
@@ -584,13 +647,17 @@ function isPrivateOrLocalHost(hostname: string): boolean {
     if (normalized === "::1") {
       return true;
     }
-    return normalized.startsWith("fc") || normalized.startsWith("fd") || normalized.startsWith("fe80");
+    return (
+      normalized.startsWith("fc") || normalized.startsWith("fd") || normalized.startsWith("fe80")
+    );
   }
 
   return false;
 }
 
-async function resolveHostname(hostname: string): Promise<Array<{ address: string; family: number }>> {
+async function resolveHostname(
+  hostname: string,
+): Promise<Array<{ address: string; family: number }>> {
   const records = await dnsLookup(hostname, { all: true, verbatim: true });
   return Array.isArray(records) ? records : [records];
 }
@@ -747,15 +814,18 @@ export async function prepareMediaInput(
     : Buffer.from(response.data as ArrayBuffer);
 
   await fsPromises.writeFile(tempPath, buffer);
+  markTrustedHostMediaPath(tempPath);
   log?.debug?.(`[DingTalk] Downloaded remote media to temp file: ${tempPath}`);
 
   return {
     path: tempPath,
     cleanup: async () => {
+      unmarkTrustedHostMediaPath(tempPath);
       try {
         await fsPromises.unlink(tempPath);
       } catch (err: unknown) {
-        const code = typeof err === "object" && err !== null && "code" in err ? err.code : undefined;
+        const code =
+          typeof err === "object" && err !== null && "code" in err ? err.code : undefined;
         if (code !== "ENOENT") {
           const message = err instanceof Error ? err.message : String(err);
           log?.warn?.(`[DingTalk] Failed to remove temp media ${tempPath}: ${message}`);
@@ -775,32 +845,163 @@ const FILE_SIZE_LIMITS: Record<DingTalkMediaType, number> = {
   file: 20 * 1024 * 1024, // 20MB
 };
 
+/**
+ * Returns true when `target` is `root` itself or a descendant of it.
+ * Uses `path.relative` so sibling paths sharing a prefix (for example
+ * `/allowed` vs `/allowed-evil`) are not treated as contained.
+ */
+function isPathWithinRoot(root: string, target: string): boolean {
+  const relative = path.relative(root, target);
+  return (
+    relative === "" ||
+    (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative))
+  );
+}
+
+/**
+ * Resolve a path for boundary comparison while tolerating paths that do not
+ * exist yet on the host (sandbox/container paths). Mirrors the runtime media
+ * bridge: prefer the fully resolved real path, fall back to resolving the
+ * parent directory, and only then fall back to a plain path resolution.
+ */
+async function resolveCanonicalMediaPath(mediaPath: string): Promise<string> {
+  try {
+    return await fsPromises.realpath(mediaPath);
+  } catch {
+    try {
+      const parent = await fsPromises.realpath(path.dirname(mediaPath));
+      return path.join(parent, path.basename(mediaPath));
+    } catch {
+      return path.resolve(mediaPath);
+    }
+  }
+}
+
+/**
+ * Canonicalize an allowed root, falling back to `path.resolve` when it is
+ * absent. Filesystem roots are rejected: authorizing `/` would allow every host
+ * path, so such an entry is treated as invalid (undefined).
+ */
+async function resolveCanonicalRoot(root: string): Promise<string | undefined> {
+  const resolved = path.resolve(root);
+  if (resolved === path.parse(resolved).root) {
+    return undefined;
+  }
+  try {
+    const real = await fsPromises.realpath(resolved);
+    return real === path.parse(real).root ? undefined : real;
+  } catch {
+    return resolved;
+  }
+}
+
+/** A host path that passed the boundary check, plus roots to re-verify after open. */
+type AllowedHostRead = {
+  path: string;
+  /** Canonical roots re-checked after opening, when a boundary is configured. */
+  roots?: readonly string[];
+};
+
+/**
+ * Resolve the host path a direct read may use, or undefined when the path falls
+ * outside the configured roots and is not a plugin-owned temp file. With no
+ * boundary configured the caller path is returned unchanged so the historical
+ * direct-read behavior is preserved.
+ */
+async function resolveAllowedHostReadPath(
+  mediaPath: string,
+  mediaLocalRoots?: string[],
+): Promise<AllowedHostRead | undefined> {
+  if (!mediaLocalRoots) {
+    return { path: mediaPath };
+  }
+  // Plugin-generated temp media (remote download / voice transcode) lives
+  // outside the roots but is not caller-controlled, so allow reading it.
+  if (isTrustedHostMediaPath(mediaPath)) {
+    return { path: path.resolve(mediaPath) };
+  }
+  // Compare canonical paths so a symlink inside an allowed root cannot redirect
+  // the read outside of it.
+  const [canonicalPath, canonicalRoots] = await Promise.all([
+    resolveCanonicalMediaPath(mediaPath),
+    Promise.all(mediaLocalRoots.map((root) => resolveCanonicalRoot(root))),
+  ]);
+  const usableRoots = canonicalRoots.filter((root): root is string => Boolean(root));
+  if (usableRoots.some((root) => isPathWithinRoot(root, canonicalPath))) {
+    return { path: canonicalPath, roots: usableRoots };
+  }
+  return undefined;
+}
+
+/**
+ * Read a boundary-validated host file without following a final-component
+ * symlink, then re-check containment while the handle is held. `O_NOFOLLOW`
+ * alone leaves a check-to-open race on intermediate directories, so the path is
+ * re-resolved against the frozen roots after opening.
+ */
+async function readVerifiedHostFile(allowed: AllowedHostRead): Promise<Buffer> {
+  const noFollow = typeof fsConstants.O_NOFOLLOW === "number" ? fsConstants.O_NOFOLLOW : 0;
+  const handle = await fsPromises.open(allowed.path, fsConstants.O_RDONLY | noFollow);
+  try {
+    if (allowed.roots) {
+      const recheck = await fsPromises.realpath(allowed.path);
+      if (!allowed.roots.some((root) => isPathWithinRoot(root, recheck))) {
+        throw Object.assign(
+          new Error(`Media path escaped the allowed roots during read: ${allowed.path}`),
+          { code: "EACCES" },
+        );
+      }
+    }
+    return await handle.readFile();
+  } finally {
+    await handle.close().catch(() => {});
+  }
+}
+
 /**
  * Read a media file, resolving sandbox/container paths via the runtime bridge
  * when direct host filesystem access fails.
  *
  * Precedence:
- *   1. Direct fs.readFile (works for host-local paths)
+ *   1. Direct host read (works for host-local paths inside the allowed roots)
  *   2. rt.media.loadWebMedia (resolves sandbox workspace paths via bridge)
+ *
+ * When `mediaLocalRoots` is configured, a direct host read is only allowed for
+ * paths whose canonical (symlink-resolved) location lives inside one of those
+ * roots, plus plugin-owned temp files. Everything else goes through the runtime
+ * media bridge so the host boundary stays enforced.
  */
 async function readMediaBuffer(
   mediaPath: string,
   options?: { mediaLocalRoots?: string[] },
   log?: Logger,
 ): Promise<{ buffer: Buffer; size: number }> {
-  // Try direct host filesystem first
-  try {
-    const buffer = await fsPromises.readFile(mediaPath);
-    return { buffer, size: buffer.length };
-  } catch (err: unknown) {
-    const errno = err as NodeJS.ErrnoException;
-    if (errno.code !== "ENOENT") {
-      throw err; // Permission errors etc. should propagate immediately
+  // Direct host reads are allowed only when no boundary is configured, the path
+  // is a plugin-owned temp file, or it canonicalizes inside an allowed root.
+  const allowed = await resolveAllowedHostReadPath(mediaPath, options?.mediaLocalRoots);
+
+  if (allowed) {
+    try {
+      const buffer = options?.mediaLocalRoots
+        ? await readVerifiedHostFile(allowed)
+        : await fsPromises.readFile(allowed.path);
+      return { buffer, size: buffer.length };
+    } catch (err: unknown) {
+      const errno = err as NodeJS.ErrnoException;
+      // ELOOP/ENOTDIR cover dangling symlinks and non-directory path
+      // components; treat them like the historical ENOENT fallback.
+      if (errno.code !== "ENOENT" && errno.code !== "ELOOP" && errno.code !== "ENOTDIR") {
+        throw err; // Permission errors etc. should propagate immediately
+      }
+      log?.debug?.(`[DingTalk] File not found on host, trying runtime media bridge: ${mediaPath}`);
     }
+  } else {
+    log?.debug?.(
+      `[DingTalk] Media path is outside configured local roots, using runtime media bridge: ${mediaPath}`,
+    );
   }
 
-  // File not found on host — try runtime media bridge (sandbox/container paths)
-  log?.debug?.(`[DingTalk] File not found on host, trying runtime media bridge: ${mediaPath}`);
+  // Fall back to runtime media bridge (sandbox/container paths)
   const rt = getDingTalkRuntime() as PluginRuntimeWithMedia;
   if (!rt.media?.loadWebMedia) {
     throw Object.assign(
@@ -814,15 +1015,12 @@ async function readMediaBuffer(
   });
 
   if (!media || !media.buffer) {
-    throw Object.assign(
-      new Error(`Runtime media bridge returned no data for: ${mediaPath}`),
-      { code: "ENOENT" },
-    );
+    throw Object.assign(new Error(`Runtime media bridge returned no data for: ${mediaPath}`), {
+      code: "ENOENT",
+    });
   }
 
-  const buffer = Buffer.isBuffer(media.buffer)
-    ? media.buffer
-    : Buffer.from(media.buffer);
+  const buffer = Buffer.isBuffer(media.buffer) ? media.buffer : Buffer.from(media.buffer);
   return { buffer, size: buffer.length };
 }
 
@@ -852,16 +1050,20 @@ export async function uploadMedia(
     let resolvedMediaPath = mediaPath;
 
     if (mediaType === "voice") {
-      const prepared = await prepareVoiceUploadPath(mediaPath, log);
+      const prepared = await prepareVoiceUploadPath(mediaPath, options, log);
       resolvedMediaPath = prepared.path;
       voicePreparedCleanup = prepared.cleanup;
     }
 
     // Read file via sandbox-aware bridge (falls back to direct fs for host paths)
     const { buffer, size } = await readMediaBuffer(resolvedMediaPath, options, log);
-    const durationMs = mediaType === "voice"
-      ? await getVoiceDurationMs(resolvedMediaPath, mediaType, log, { ...options, preReadBuffer: buffer })
-      : undefined;
+    const durationMs =
+      mediaType === "voice"
+        ? await getVoiceDurationMs(resolvedMediaPath, mediaType, log, {
+            ...options,
+            preReadBuffer: buffer,
+          })
+        : undefined;
 
     // Check file size
     const sizeLimit = FILE_SIZE_LIMITS[mediaType];
@@ -908,7 +1110,9 @@ export async function uploadMedia(
     } else if (errno.code === "EACCES") {
       log?.error?.(`[DingTalk] Permission denied accessing media file: ${mediaPath}`);
     } else {
-      log?.error?.(`[DingTalk] Failed to upload media: ${err instanceof Error ? err.message : String(err)}`);
+      log?.error?.(
+        `[DingTalk] Failed to upload media: ${err instanceof Error ? err.message : String(err)}`,
+      );
       if (axios.isAxiosError(err) && err.response) {
         const status = err.response.status;
         const statusText = err.response.statusText;

package/src/{message-context-store.ts → messaging/message-context-store.ts}

@@ -1,6 +1,6 @@
 import { randomUUID } from "node:crypto";
-import { readNamespaceJson, writeNamespaceJsonAtomic } from "./persistence-store";
-import type { AttachmentTextSource, Logger, QuotedRef } from "./types";
+import type { AttachmentTextSource, Logger, QuotedRef } from "../platform/types";
+import { readNamespaceJson, writeNamespaceJsonAtomic } from "../shared/persistence-store";
 
 const MESSAGE_CONTEXT_NAMESPACE = "messages.context";
 const MESSAGE_CONTEXT_VERSION = 1;
@@ -50,7 +50,10 @@ export interface MessageRecord {
   quotedRef?: QuotedRef;
   senderId?: string;
   senderName?: string;
+  /** Display names parsed from mentions; not positionally aligned with mentionUserIds. */
   mentions?: string[];
+  /** Raw DingTalk user IDs from structured @mention payloads (atUsers / richText atUserId). Not positionally aligned with mentions. */
+  mentionUserIds?: string[];
   chatType?: "direct" | "group";
   /** Flat quoted target for summary/history lookups; quotedRef remains the authoritative structured link. */
   quotedMessageId?: string;
@@ -101,7 +104,10 @@ interface BaseUpsertParams {
   quotedRef?: QuotedRef;
   senderId?: string;
   senderName?: string;
+  /** Display names parsed from mentions; not positionally aligned with mentionUserIds. */
   mentions?: string[];
+  /** Raw DingTalk user IDs from structured @mention payloads (atUsers / richText atUserId). Not positionally aligned with mentions. */
+  mentionUserIds?: string[];
   chatType?: "direct" | "group";
   quotedMessageId?: string;
   media?: {
@@ -340,6 +346,7 @@ function normalizeMessageRecord(value: unknown): MessageRecord | null {
         ? candidate.senderName.trim()
         : undefined,
     mentions: normalizeMentions(candidate.mentions),
+    mentionUserIds: normalizeMentions(candidate.mentionUserIds),
     chatType:
       candidate.chatType === "direct" || candidate.chatType === "group"
         ? candidate.chatType
@@ -703,6 +710,7 @@ function upsertRecord(
     senderId?: string;
     senderName?: string;
     mentions?: string[];
+    mentionUserIds?: string[];
     chatType?: "direct" | "group";
     quotedMessageId?: string;
     media?: MessageRecord["media"];
@@ -765,6 +773,7 @@ function upsertRecord(
     senderId: mergeStringField(existing?.senderId, params.senderId),
     senderName: mergeStringField(existing?.senderName, params.senderName),
     mentions: mergeMentions(existing?.mentions, params.mentions),
+    mentionUserIds: mergeMentions(existing?.mentionUserIds, params.mentionUserIds),
     chatType: params.chatType || existing?.chatType,
     quotedMessageId: mergeStringField(existing?.quotedMessageId, params.quotedMessageId),
     media: mergeMedia(existing?.media, params.media),