@powercess/qq-mcp 0.2.0

package/src/keyscan.ts

@@ -0,0 +1,202 @@
+/**
+ * Offline key (device passphrase) capture for NTQQ.
+ *
+ * The passphrase is never stored on disk by QQ: it is derived in-process and
+ * handed to SQLCipher. It is, however, a short ASCII string living in the QQ
+ * process, and it is the same for every database on the device. This module
+ * scrapes candidate tokens from process memory and accepts the first one that
+ * actually decrypts a known artefact (a `.material` DDL blob or page 1 of a
+ * database), so a candidate is only reported when it is verified.
+ */
+import { execFile } from "node:child_process";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { availableParallelism } from "node:os";
+import { dirname } from "node:path";
+import { Worker } from "node:worker_threads";
+import { decryptMaterial } from "./schema.js";
+import { verifyPassphrase } from "./sqlcipher.js";
+import { findQQDataDirs, KEY_FILE, listDataSources, SCANNER_SCRIPT, type DataSource } from "./offline.js";
+
+const PYTHON = process.env.QQ_MCP_PYTHON ?? "python";
+
+/** A cheap, verifiable fact that a candidate passphrase must reproduce. */
+export type KeyOracle =
+  | { kind: "material"; materialPath: string }
+  | { kind: "database"; dbPath: string };
+
+/** Tests one candidate against the oracle. Wrong candidates fail structurally. */
+export function verifyKeyCandidate(oracle: KeyOracle, candidate: string): boolean {
+  try {
+    if (oracle.kind === "material") {
+      const { plaintext } = decryptMaterial(oracle.materialPath, candidate);
+      return plaintext.includes(Buffer.from("CREATE TABLE", "utf8"));
+    }
+    return verifyPassphrase(oracle.dbPath, candidate);
+  } catch {
+    return false;
+  }
+}
+
+/** PIDs of running `QQ.exe` processes (Windows). */
+export function findQQPids(): Promise<number[]> {
+  const { promise, resolve, reject } = Promise.withResolvers<number[]>();
+  execFile(
+    "powershell",
+    ["-NoProfile", "-Command", "(Get-Process -Name 'QQ' -ErrorAction SilentlyContinue).Id"],
+    { windowsHide: true },
+    (error, stdout) => {
+      if (error) {
+        reject(error);
+        return;
+      }
+      const pids = stdout
+        .split(/\s+/)
+        .map((s) => Number.parseInt(s, 10))
+        .filter((n) => Number.isInteger(n) && n > 0);
+      resolve(pids);
+    }
+  );
+  return promise;
+}
+
+/** Picks a verification oracle from the locally installed QQ data. */
+export function pickOracle(opts: { materialPath?: string; dbPath?: string; sources?: DataSource[] } = {}): KeyOracle | undefined {
+  if (opts.materialPath) return { kind: "material", materialPath: opts.materialPath };
+  if (opts.dbPath) return { kind: "database", dbPath: opts.dbPath };
+  const sources = opts.sources ?? listDataSources();
+  const withMaterial = sources.find((s) => s.materialPath && s.name.startsWith("nt_msg"));
+  if (withMaterial?.materialPath) return { kind: "material", materialPath: withMaterial.materialPath };
+  const anyMaterial = sources.find((s) => s.materialPath);
+  if (anyMaterial?.materialPath) return { kind: "material", materialPath: anyMaterial.materialPath };
+  const anyUsable = sources.find((s) => s.pages > 0);
+  if (anyUsable) return { kind: "database", dbPath: anyUsable.dbPath };
+  return undefined;
+}
+
+export interface CaptureOptions {
+  pids?: number[];
+  materialPath?: string;
+  dbPath?: string;
+  maxCandidates?: number;
+  /** Override the memory scanner path (used by tests). */
+  scannerPath?: string;
+  /** Persist the recovered passphrase to the `qqkey` file in {@link KEY_FILE}. */
+  save?: boolean;
+  onProgress?: (message: string) => void;
+}
+
+export interface CaptureResult {
+  passphrase?: string;
+  oracle?: KeyOracle;
+  pidsScanned: number[];
+  candidates: number;
+  testedInParallel: number;
+  elapsedMs: number;
+  savedTo?: string;
+}
+
+/** Scrapes candidate tokens from QQ's memory and verifies them against a key oracle. */
+export async function captureOfflineKey(opts: CaptureOptions = {}): Promise<CaptureResult> {
+  const started = Date.now();
+  const sources = listDataSources();
+  const oracle = pickOracle({ materialPath: opts.materialPath, dbPath: opts.dbPath, sources });
+  if (!oracle) {
+    throw new Error("no verification oracle: pass materialPath or dbPath (no NTQQ databases found locally)");
+  }
+  const pids = opts.pids?.length ? opts.pids : await findQQPids();
+  if (pids.length === 0) throw new Error("QQ is not running — log in first, then retry");
+  const scanner = opts.scannerPath ?? SCANNER_SCRIPT;
+  if (!existsSync(scanner)) throw new Error(`missing memory scanner: ${scanner}`);
+
+  opts.onProgress?.(`scanning ${pids.length} process(es) for candidates`);
+  const candidates = await runScanner(scanner, pids, opts.maxCandidates ?? 200_000);
+  opts.onProgress?.(`testing ${candidates.length} candidates against ${oracle.kind}`);
+  const found = await verifyCandidates(oracle, candidates, opts.onProgress);
+
+  const result: CaptureResult = {
+    passphrase: found.passphrase,
+    oracle,
+    pidsScanned: pids,
+    candidates: candidates.length,
+    testedInParallel: found.tested,
+    elapsedMs: Date.now() - started,
+  };
+  if (found.passphrase && opts.save) {
+    mkdirSync(dirname(KEY_FILE), { recursive: true });
+    writeFileSync(KEY_FILE, `${found.passphrase}\n`, { encoding: "utf8", mode: 0o600 });
+    result.savedTo = KEY_FILE;
+  }
+  return result;
+}
+
+function runScanner(scanner: string, pids: number[], maxCandidates: number): Promise<string[]> {
+  const { promise, resolve, reject } = Promise.withResolvers<string[]>();
+  execFile(
+    PYTHON,
+    [scanner, ...pids.map(String), "--max", String(maxCandidates)],
+    { windowsHide: true, timeout: 900_000, maxBuffer: 64 * 1024 * 1024 },
+    (error, stdout, stderr) => {
+      if (error && !stdout) {
+        reject(new Error(`memory scan failed: ${stderr || error.message}`));
+        return;
+      }
+      const seen = new Set<string>();
+      for (const line of stdout.split(/\r?\n/)) {
+        const token = line.trim();
+        if (token.length >= 12 && token.length <= 32) seen.add(token);
+      }
+      resolve([...seen]);
+    }
+  );
+  return promise;
+}
+
+interface VerifyOutcome {
+  passphrase?: string;
+  tested: number;
+}
+
+/** Fans candidates across workers; returns as soon as one worker verifies a key. */
+async function verifyCandidates(
+  oracle: KeyOracle,
+  candidates: string[],
+  onProgress?: (message: string) => void
+): Promise<VerifyOutcome> {
+  if (candidates.length === 0) return { tested: 0 };
+  const workers = Math.max(1, Math.min(availableParallelism(), 16, candidates.length));
+  const chunkSize = Math.ceil(candidates.length / workers);
+  const chunks: string[][] = [];
+  for (let i = 0; i < candidates.length; i += chunkSize) chunks.push(candidates.slice(i, i + chunkSize));
+  const workerUrl = new URL("./verify-worker.js", import.meta.url);
+  const running = chunks.map(
+    (chunk) =>
+      new Promise<VerifyOutcome>((resolve, reject) => {
+        const worker = new Worker(workerUrl, { workerData: { oracle, candidates: chunk } });
+        worker.once("message", (message: { passphrase?: string; tested: number }) => {
+          resolve({ passphrase: message.passphrase, tested: message.tested });
+        });
+        worker.once("error", reject);
+      })
+  );
+  const outcomes = running.map(async (promise, index) => {
+    const outcome = await promise;
+    onProgress?.(`worker ${index + 1}/${running.length} tested ${outcome.tested}`);
+    return outcome;
+  });
+  const settled = await Promise.allSettled(outcomes);
+  let tested = 0;
+  let passphrase: string | undefined;
+  for (const entry of settled) {
+    if (entry.status !== "fulfilled") continue;
+    tested += entry.value.tested;
+    if (!passphrase && entry.value.passphrase) passphrase = entry.value.passphrase;
+  }
+  return { passphrase, tested };
+}
+
+/** Convenience: verifies a known passphrase against every locally found database. */
+export function verifyPassphraseEverywhere(passphrase: string): Array<{ name: string; ok: boolean }> {
+  return listDataSources().map((source) => ({ name: source.name, ok: verifyPassphrase(source.dbPath, passphrase) }));
+}
+
+export { findQQDataDirs };

package/src/messages.ts

@@ -0,0 +1,414 @@
+/**
+ * Protobuf decoding of NTQQ message bodies.
+ *
+ * `c2c_msg_table.[40800]` / `group_msg_table.[40800]` hold a protobuf
+ * `MsgBody { repeated MsgContent content = 40800 }`. Field ids below were
+ * verified against this account's local database and cross-checked with the
+ * public field research (QQBackup/nt_msg_db_util, `msgdb/proto/c2c_40800.proto`).
+ */
+export interface WireField {
+  field: number;
+  wire: number;
+  /** varint/fixed value for numeric fields. */
+  value?: bigint;
+  /** payload for length-delimited fields. */
+  bytes?: Buffer;
+}
+
+export const MSG_BODY_CONTENT_FIELD = 40800;
+
+/** Decodes one protobuf message level into its wire fields. */
+export function decodeWireFields(buf: Buffer, maxFields = 512): WireField[] {
+  const out: WireField[] = [];
+  let off = 0;
+  while (off < buf.length && out.length < maxFields) {
+    const [tag, afterTag] = readVarint(buf, off);
+    off = afterTag;
+    const field = Number(tag >> 3n);
+    const wire = Number(tag & 7n);
+    if (wire === 0) {
+      const [value, next] = readVarint(buf, off);
+      off = next;
+      out.push({ field, wire, value });
+    } else if (wire === 2) {
+      const [len, next] = readVarint(buf, off);
+      off = next;
+      const end = off + Number(len);
+      if (end > buf.length) throw new Error(`field ${field}: length ${len} exceeds buffer`);
+      out.push({ field, wire, bytes: buf.subarray(off, end) });
+      off = end;
+    } else if (wire === 5) {
+      out.push({ field, wire, value: BigInt(buf.readUInt32LE(off)) });
+      off += 4;
+    } else if (wire === 1) {
+      out.push({ field, wire, value: buf.readBigUInt64LE(off) });
+      off += 8;
+    } else {
+      throw new Error(`field ${field}: unsupported wire type ${wire}`);
+    }
+  }
+  return out;
+}
+
+function readVarint(buf: Buffer, off: number): [bigint, number] {
+  let value = 0n;
+  let shift = 0n;
+  let i = off;
+  while (i < buf.length) {
+    const byte = buf[i++];
+    value |= BigInt(byte & 0x7f) << shift;
+    if ((byte & 0x80) === 0) return [value, i];
+    shift += 7n;
+    if (shift > 63n) break;
+  }
+  throw new Error(`varint overflow at ${off}`);
+}
+
+export type SegmentType =
+  | "text"
+  | "image"
+  | "video"
+  | "file"
+  | "sticker"
+  | "contact"
+  | "ark"
+  | "nudge"
+  | "call"
+  | "reply"
+  | "forward"
+  | "legacy_forward"
+  | "system"
+  | "unknown";
+
+export interface MessageSegment {
+  type: SegmentType;
+  /** Plain text for `text` segments, or the summary of media segments. */
+  text?: string;
+  filename?: string;
+  fileExt?: string;
+  fileSize?: number;
+  fileUuid?: string;
+  /** Lowercase hex of the raw md5 field when present. */
+  md5?: string;
+  width?: number;
+  height?: number;
+  /** CDN download URLs (fields 45802-45804). */
+  urls?: string[];
+  cdnHost?: string;
+  msgId?: string;
+  contentType?: number;
+  replyMsgId?: string;
+  replySummary?: string;
+  callType?: number;
+  callDuration?: number;
+  callDesc?: string;
+  systemContent?: string;
+  /** Contact-card payload (fields 47702-47715): shared nickname/uid/remark. */
+  contact?: { relation?: number; uid?: string; nickname?: string; remark?: string };
+  /** Interactive card (`ark`) payload (fields 48401-48421) with its opaque ids. */
+  card?: { appId?: string; token?: string; template?: string };
+  /** Nudge ("戳一戳") payload, carried by message type 5 rows. */
+  nudge?: { action?: string; suffix?: string; image?: string; parties?: Array<{ uid?: string; nickname?: string }> };
+  /** Field ids seen in the blob but not modelled, so callers can spot gaps. */
+  unmodelledFields?: number[];
+}
+
+export interface DecodedMessageContent {
+  segments: MessageSegment[];
+  /** Concatenated text of every segment, for search and preview. */
+  text: string;
+  /** Single segment type, `mixed` for several kinds, `unknown` when empty. */
+  kind: SegmentType | "mixed";
+  /** Unix seconds from the inner protobuf timestamp (field 49155) when present. */
+  innerTimestamp?: number;
+  protoVersion?: string;
+}
+
+const IMAGE_EXT: Record<string, true> = {
+  jpg: true, jpeg: true, png: true, gif: true, webp: true, bmp: true, heic: true, avif: true,
+};
+const VIDEO_EXT: Record<string, true> = {
+  mp4: true, mov: true, mkv: true, avi: true, webm: true, m4v: true, wmv: true,
+};
+/** MsgContent fields this module models; everything else is reported as unmodelled. */
+const MODELLED_FIELDS: Record<number, true> = {
+  5: true, 40010: true, 40020: true, 40021: true, 45001: true, 45002: true, 45003: true, 45004: true,
+  45101: true, 45102: true, 45103: true, 45104: true, 45105: true, 45106: true, 45108: true, 45109: true,
+  45110: true, 45111: true, 45112: true, 45402: true, 45403: true, 45404: true, 45405: true, 45406: true,
+  45407: true, 45408: true, 45409: true, 45410: true, 45411: true, 45412: true, 45413: true, 45414: true,
+  45415: true, 45416: true, 45418: true, 45419: true, 45421: true, 45422: true, 45423: true, 45424: true,
+  45501: true, 45503: true, 45504: true, 45505: true, 45507: true, 45509: true, 45510: true, 45511: true,
+  45512: true, 45513: true, 45514: true, 45515: true, 45516: true, 45517: true, 45518: true, 45519: true,
+  45526: true, 45550: true, 45600: true, 45801: true, 45802: true, 45803: true, 45804: true, 45805: true,
+  45806: true, 45807: true, 45812: true, 45814: true, 45815: true, 45816: true, 45817: true, 45818: true,
+  45819: true, 45820: true, 45821: true, 45822: true, 45823: true, 45824: true, 45825: true, 45826: true,
+  45827: true, 45828: true, 45829: true, 45851: true, 45852: true, 45853: true, 45854: true, 45855: true,
+  45856: true, 45857: true, 45858: true, 45859: true, 45860: true, 45861: true, 45862: true, 45863: true,
+  45906: true, 45907: true, 45909: true, 45911: true, 45922: true, 45923: true, 45924: true, 45925: true,
+  45926: true, 45954: true, 45974: true, 47401: true, 47402: true, 47403: true, 47404: true, 47413: true,
+  47421: true, 47422: true, 47423: true, 47501: true, 47502: true, 47601: true, 47602: true, 47603: true,
+  47604: true, 47605: true, 47606: true, 47607: true, 47608: true, 47609: true, 47610: true, 47611: true,
+  47612: true, 47613: true, 47614: true, 47615: true, 47616: true, 47617: true, 47618: true, 47619: true,
+  47620: true, 47622: true, 47702: true, 47703: true, 47704: true, 47705: true, 47706: true, 47710: true,
+  47711: true, 47713: true, 47714: true, 47715: true, 47901: true, 47902: true, 47904: true, 48151: true,
+  48152: true, 48153: true, 48154: true, 48155: true, 48156: true, 48157: true, 48210: true, 48211: true,
+  48212: true, 48213: true, 48214: true, 48215: true, 48216: true, 48217: true, 48218: true, 48271: true,
+  48272: true, 48273: true, 48275: true, 48401: true, 48402: true, 48403: true, 48404: true, 48405: true,
+  48406: true, 48407: true, 48408: true, 48409: true, 48410: true, 48411: true, 48412: true, 48417: true,
+  48418: true, 48419: true, 48421: true, 48601: true, 48602: true, 48603: true, 49154: true, 49155: true,
+  80810: true, 80824: true, 80900: true, 80901: true, 80902: true, 80903: true, 80905: true, 80908: true,
+  80909: true, 80910: true, 80935: true, 80941: true, 80942: true, 80970: true, 80975: true, 80980: true,
+  80981: true, 80983: true, 80995: true, 95654: true, 48542: true,
+};
+const STICKER_SUMMARY = "[动画表情]";
+
+/** Decodes the `[40800]` blob of a message row into typed segments. */
+export function decodeMessageContent(blob: Buffer | Uint8Array, maxFields = 512): DecodedMessageContent {
+  const buf = Buffer.isBuffer(blob) ? blob : Buffer.from(blob);
+  const fields = decodeWireFields(buf, maxFields);
+  const segments: MessageSegment[] = [];
+  let innerTimestamp: number | undefined;
+  let protoVersion: string | undefined;
+  for (const field of fields) {
+    if (field.field === MSG_BODY_CONTENT_FIELD && field.bytes) {
+      segments.push(decodeSegment(field.bytes));
+      continue;
+    }
+    if (field.field === 49155 && field.value !== undefined) innerTimestamp = Number(field.value);
+    if (field.field === 49154 && field.bytes) protoVersion = asText(field.bytes);
+  }
+  const text = segments
+    .map((s) => s.text ?? "")
+    .filter((t) => t.length > 0)
+    .join("\n");
+  const kinds = new Set(segments.map((s) => s.type));
+  const kind: DecodedMessageContent["kind"] =
+    kinds.size === 1 ? segments[0]?.type ?? "unknown" : kinds.size > 1 ? "mixed" : "unknown";
+  return { segments, text, kind, innerTimestamp, protoVersion };
+}
+
+function decodeSegment(buf: Buffer): MessageSegment {
+  const fields = decodeWireFields(buf);
+  const byId = new Map<number, WireField>();
+  for (const f of fields) if (!byId.has(f.field)) byId.set(f.field, f);
+  const all = (id: number): WireField[] => fields.filter((f) => f.field === id);
+  const textFallbacks = all(45815)
+    .map((f) => asText(f.bytes ?? Buffer.alloc(0)))
+    .filter(Boolean);
+
+  const num = (id: number): number | undefined => {
+    const v = byId.get(id)?.value;
+    return v === undefined ? undefined : Number(v);
+  };
+  const str = (id: number): string | undefined => {
+    const b = byId.get(id)?.bytes;
+    return b ? asText(b) : undefined;
+  };
+  const raw = (id: number): Buffer | undefined => byId.get(id)?.bytes;
+
+  const filename = str(45402);
+  const fileExt = (str(45419)?.replace(/^\./, "") ?? filename?.split(".").pop() ?? "").toLowerCase() || undefined;
+  const md5Raw = raw(45406);
+  const urls = [45802, 45803, 45804].map(str).filter((u): u is string => Boolean(u));
+  const summary = textFallbacks[0] ?? str(45422) ?? str(45812) ?? str(80900);
+  const unmodelledFields = unmappedFields(byId);
+  const msgIdValue = byId.get(45001)?.value;
+
+  const segment: MessageSegment = {
+    type: "unknown",
+    msgId: msgIdValue === undefined ? undefined : String(msgIdValue),
+    contentType: num(45002),
+    filename,
+    fileExt,
+    fileSize: num(45405),
+    fileUuid: str(45503),
+    md5: md5Raw && md5Raw.length >= 16 ? md5Raw.subarray(0, 16).toString("hex") : undefined,
+    width: num(45411),
+    height: num(45412),
+    urls,
+    cdnHost: str(45816),
+    unmodelledFields,
+  };
+
+  const callType = num(48151);
+  if (callType !== undefined || str(48153) !== undefined) {
+    return { ...segment, type: "call", callType, callDuration: num(48152), callDesc: str(48153), text: str(48153) ?? summary };
+  }
+  const systemContent = str(80900);
+  if (systemContent !== undefined) {
+    return { ...segment, type: "system", systemContent, text: systemContent };
+  }
+  const contactNickname = str(47705) ?? str(47714);
+  if (contactNickname !== undefined || str(47703) !== undefined) {
+    const contact = {
+      relation: num(47702),
+      uid: str(47703) ?? str(47704),
+      nickname: contactNickname,
+      remark: str(47706) ?? str(47715),
+    };
+    return { ...segment, type: "contact", contact, text: summary ?? contact.nickname ?? contact.remark ?? "[名片]" };
+  }
+  const cardAppId = str(48409);
+  if (cardAppId !== undefined || raw(48403) !== undefined) {
+    const card = { appId: cardAppId, token: str(48410) ?? str(48418), template: str(48402) };
+    return { ...segment, type: "ark", card, text: summary ?? "[卡片消息]" };
+  }
+  const tipXml = str(48214) ?? str(48271);
+  if (tipXml !== undefined) {
+    const pairs = fieldPairs(all(48217));
+    const parties = fieldPairs(all(48210)).map(([uid, nickname]) => ({ uid, nickname: nickname || undefined }));
+    const nudge = {
+      action: pairs.find(([key]) => key === "action_str")?.[1],
+      suffix: pairs.find(([key]) => key === "suffix_str")?.[1],
+      image: pairs.find(([key]) => key === "action_img_url")?.[1],
+      parties: parties.length ? parties : undefined,
+    };
+    return { ...segment, type: "nudge", nudge, text: summary ?? tipText(tipXml) ?? "[互动消息]" };
+  }
+  const isImageExt = fileExt !== undefined && IMAGE_EXT[fileExt] === true;
+  const isVideoExt = fileExt !== undefined && VIDEO_EXT[fileExt] === true;
+  if (num(47601)) {
+    return { ...segment, type: "video", text: summary ?? (filename ? `[视频] ${filename}` : "[视频]") };
+  }
+  if (raw(45600) || summary === STICKER_SUMMARY) {
+    return { ...segment, type: "sticker", text: summary ?? "[表情]" };
+  }
+  if (isVideoExt) {
+    return { ...segment, type: "video", text: summary ?? `[视频] ${filename}` };
+  }
+  if (isImageExt || (fileExt === undefined && filename !== undefined && (num(45411) ?? 0) > 0 && (num(45412) ?? 0) > 0)) {
+    return { ...segment, type: "image", text: summary ?? (filename ? `[图片] ${filename}` : "[图片]") };
+  }
+  const legacyXml = str(48602);
+  if (legacyXml !== undefined) {
+    return { ...segment, type: "legacy_forward", text: str(47901) ?? legacyXml.slice(0, 200) };
+  }
+  if (str(47901) !== undefined || str(47904) !== undefined) {
+    return { ...segment, type: "forward", text: str(47901) ?? summary ?? "[合并转发]" };
+  }
+  const replyMsgIdValue = byId.get(47401)?.value;
+  if (replyMsgIdValue !== undefined) {
+    const replySummary = str(47413);
+    return {
+      ...segment,
+      type: "reply",
+      replyMsgId: String(replyMsgIdValue),
+      replySummary,
+      text: summary ?? replySummary ?? "[引用]",
+    };
+  }
+  if (filename !== undefined || num(45405) !== undefined) {
+    return { ...segment, type: "file", text: summary ?? (filename ? `[文件] ${filename}` : "[文件]") };
+  }
+  const text = str(45101);
+  if (text !== undefined) return { ...segment, type: "text", text };
+  return { ...segment, type: "unknown", text: summary };
+}
+
+/** Reads repeated sub-messages that encode `{key, value}` string pairs. */
+function fieldPairs(fields: WireField[]): Array<[string, string]> {
+  const out: Array<[string, string]> = [];
+  for (const field of fields) {
+    if (!field.bytes) continue;
+    const parts = decodeWireFields(field.bytes)
+      .filter((inner) => inner.bytes)
+      .map((inner) => asText(inner.bytes!));
+    if (parts.length >= 2) out.push([parts[0], parts[1]]);
+    else if (parts.length === 1) out.push([parts[0], ""]);
+  }
+  return out;
+}
+
+/** Renders a nudge tip payload: JSON items when parseable, else its XML text. */
+function tipText(raw: string): string | undefined {
+  if (raw.startsWith("{")) {
+    try {
+      const parsed = JSON.parse(raw) as { items?: Array<{ txt?: string; nm?: string }> };
+      const parts = (parsed.items ?? []).map((item) => item.txt ?? item.nm ?? "").filter(Boolean);
+      if (parts.length) return parts.join("");
+    } catch {
+      // Fall through to the XML path.
+    }
+  }
+  const parts = [...raw.matchAll(/(?:txt|nm)="([^"]*)"/g)].map((match) => match[1]).filter(Boolean);
+  return parts.length ? parts.join("") : undefined;
+}
+
+function unmappedFields(byId: Map<number, WireField>): number[] | undefined {
+  const ids: number[] = [];
+  for (const id of byId.keys()) if (MODELLED_FIELDS[id] !== true) ids.push(id);
+  return ids.length ? ids.sort((a, b) => a - b) : undefined;
+}
+
+function asText(buf: Buffer): string {
+  return buf.toString("utf8").replace(/\0+$/, "");
+}
+
+export interface MessageRecord {
+  msgId: string;
+  timestamp: number;
+  iso: string;
+  direction: number;
+  chatType: "c2c" | "group";
+  senderQq?: number;
+  senderUid?: string;
+  senderName?: string;
+  peerQq?: number;
+  groupQq?: number;
+  msgType?: number;
+  kind: string;
+  text: string;
+  segments: MessageSegment[];
+}
+
+/** Row shape expected by {@link toMessageRecord}, decoupled from the SQL layer. */
+export interface RawMessageRow {
+  msgId: unknown;
+  msgType: unknown;
+  direction: unknown;
+  senderUid: unknown;
+  peerUid: unknown;
+  senderQq: unknown;
+  peerQq: unknown;
+  /** `[40027]`: the group number for group chats, a constant for c2c rows. */
+  conversationId: unknown;
+  timestamp: unknown;
+  senderName: unknown;
+  body: unknown;
+}
+
+export function toMessageRecord(row: RawMessageRow, chatType: "c2c" | "group"): MessageRecord {
+  const decoded = row.body ? decodeMessageContent(row.body as Buffer) : { segments: [], text: "", kind: "unknown" };
+  const timestamp = Number(row.timestamp ?? 0);
+  // Group rows sometimes carry 0 in the peer column (system messages); the
+  // conversation column holds the group number in every row.
+  const groupQq = asNumber(row.conversationId) ?? asNumber(row.peerQq);
+  return {
+    msgId: String(row.msgId ?? ""),
+    timestamp,
+    iso: timestamp ? new Date(timestamp * 1000).toISOString() : "",
+    direction: Number(row.direction ?? 0),
+    chatType,
+    senderQq: asNumber(row.senderQq),
+    senderUid: asOptionalString(row.senderUid),
+    senderName: asOptionalString(row.senderName),
+    peerQq: asNumber(row.peerQq),
+    groupQq: chatType === "group" ? groupQq : undefined,
+    msgType: asNumber(row.msgType),
+    kind: decoded.kind,
+    text: decoded.text,
+    segments: decoded.segments,
+  };
+}
+
+function asNumber(value: unknown): number | undefined {
+  if (value === null || value === undefined) return undefined;
+  const n = Number(value);
+  return Number.isFinite(n) ? n : undefined;
+}
+
+function asOptionalString(value: unknown): string | undefined {
+  if (value === null || value === undefined) return undefined;
+  const s = String(value);
+  return s.length ? s : undefined;
+}