@chainlesschain/personal-data-hub 0.3.9 → 0.4.0

package/lib/adapters/wechat-pc/index.js

@@ -0,0 +1,335 @@
+"use strict";
+
+/**
+ * WeChat **desktop (PC)** adapter — 本地直读样板 (ported from social-douyin's
+ * im.db direct-read). Reads PC WeChat's local SQLite DBs straight into the
+ * vault:
+ *
+ *   - MSG0.db..MSGN.db   → table MSG      → 私信/群消息 (message events)
+ *   - MicroMsg.db        → table Contact  → 联系人 (contact persons)
+ *
+ * Distinct from the Android `wechat` adapter (EnMicroMsg.db / frida key /
+ * message+rcontact schema). PC WeChat has its own schema + a 32-byte raw
+ * SQLCipher key. See pc-db-reader.js for the open/decrypt details.
+ *
+ * Modes (sync opts):
+ *   1. opts.dbPath / opts.inputPath  — a PC WeChat DB file. If opts.key
+ *      (64-hex) is supplied, the reader decrypts via SQLCipher; otherwise it
+ *      expects an already-decrypted plaintext DB (the reliable, recommended
+ *      path — decrypt once with PyWxDump/手动, then point here).
+ *   2. (snapshot mode reserved for a future Android-side PC-bridge; not v0.)
+ *
+ * The reader extracts whatever of {MSG, Contact} a given file has, so call
+ * sync once per file (MSG*.db for messages, MicroMsg.db for contacts).
+ *
+ * Person ids use the SAME `person-wechat-<wxid>` + `wechatId` identifier as
+ * the Android wechat adapter, so EntityResolver merges PC + Android contacts.
+ */
+
+const fs = require("node:fs");
+const { newId } = require("../../ids");
+const {
+  ENTITY_TYPES,
+  PERSON_SUBTYPES,
+  EVENT_SUBTYPES,
+  CAPTURED_BY,
+} = require("../../constants");
+
+const NAME = "wechat-pc";
+const VERSION = "0.1.0";
+
+const KIND_MESSAGE = "message";
+const KIND_CONTACT = "contact";
+
+function stableOriginalId(kind, id) {
+  const safe =
+    (typeof id === "string" && id.length > 0 && id) ||
+    (typeof id === "number" && Number.isFinite(id) && String(id)) ||
+    `unknown-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  return `wechat-pc:${kind}:${safe}`;
+}
+
+function wxidToPersonId(wxid) {
+  return wxid ? `person-wechat-${wxid}` : null;
+}
+
+class WeChatPcAdapter {
+  constructor(opts = {}) {
+    this._dbPath = opts.dbPath || null;
+    this._key = opts.key || null;
+
+    this.name = NAME;
+    this.version = VERSION;
+    this.capabilities = [
+      "sync:sqlite",
+      "decrypt:sqlcipher-pc",
+      "parse:wechat-pc-message",
+      "parse:wechat-pc-contact",
+    ];
+    this.extractMode = "device-pull";
+    this.rateLimits = {};
+    this.dataDisclosure = {
+      fields: [
+        "wechat-pc:messages (StrTalker / StrContent / CreateTime / IsSender from MSG*.db)",
+        "wechat-pc:contacts (UserName / NickName / Remark from MicroMsg.db)",
+      ],
+      sensitivity: "high",
+      legalGate: true, // chat history — first-use 法律 gate (mirrors wechat)
+    };
+
+    this._deps = {
+      fs,
+      // DI seam: tests inject a fake SQLite driver class via dbDriverFactory.
+      dbDriverFactory: opts.dbDriverFactory || null,
+    };
+  }
+
+  async authenticate(ctx = {}) {
+    // Cheap readiness probe — never opens / decrypts a DB.
+    if (ctx && ctx.readinessOnly) {
+      if (this._dbPath) return { ok: true, mode: "configured" };
+      return {
+        ok: false,
+        reason: "DB_NOT_PULLED",
+        message:
+          "wechat-pc: 需提供 PC 微信本地数据库路径（MSG*.db / MicroMsg.db），加密库需先解密或提供 key",
+      };
+    }
+    const dbPath = (ctx && ctx.inputPath) || (ctx && ctx.dbPath) || this._dbPath;
+    if (dbPath) {
+      try {
+        this._deps.fs.accessSync(dbPath, this._deps.fs.constants.R_OK);
+      } catch (err) {
+        return {
+          ok: false,
+          reason: "INPUT_PATH_UNREADABLE",
+          message: `wechat-pc: db not readable at ${dbPath}: ${err.message}`,
+        };
+      }
+      return { ok: true, mode: "sqlite" };
+    }
+    return {
+      ok: false,
+      reason: "DB_NOT_PULLED",
+      message: "wechat-pc.authenticate: needs opts.dbPath / inputPath (MSG*.db or MicroMsg.db)",
+    };
+  }
+
+  async healthCheck() {
+    return { ok: true, lastChecked: Date.now() };
+  }
+
+  async *sync(opts = {}) {
+    const dbPath = opts.dbPath || opts.inputPath || this._dbPath;
+    if (!dbPath) {
+      throw new Error(
+        "wechat-pc.sync: needs opts.dbPath / opts.inputPath pointing to a PC WeChat DB (MSG*.db or MicroMsg.db)",
+      );
+    }
+    if (!this._deps.fs.existsSync(dbPath)) return;
+
+    // eslint-disable-next-line global-require
+    const { readPcWeChat } = require("./pc-db-reader");
+    const readOpts = { key: opts.key || this._key || null };
+    if (Number.isInteger(opts.limitMessages)) readOpts.limitMessages = opts.limitMessages;
+    if (Number.isInteger(opts.limitContacts)) readOpts.limitContacts = opts.limitContacts;
+    if (this._deps.dbDriverFactory) readOpts._databaseClass = this._deps.dbDriverFactory();
+
+    const { messages, contacts, diagnostic } = readPcWeChat(dbPath, readOpts);
+    if (typeof opts.onProgress === "function") {
+      try {
+        opts.onProgress({ phase: "pc-db-read", adapter: NAME, ...diagnostic });
+      } catch (_e) { /* progress best-effort */ }
+    }
+
+    const include = opts.include || {};
+    const limit = Number.isInteger(opts.limit) && opts.limit > 0 ? opts.limit : Infinity;
+    const fallbackCapturedAt = Date.now();
+    let emitted = 0;
+
+    if (include[KIND_MESSAGE] !== false) {
+      for (const m of messages) {
+        if (emitted >= limit) return;
+        if (!m || typeof m !== "object") continue;
+        const capturedAt =
+          typeof m.createdTimeMs === "number" && m.createdTimeMs > 0
+            ? m.createdTimeMs
+            : fallbackCapturedAt;
+        // Composite id: msgSvrId is globally unique; fallback to talker+time.
+        const idPart =
+          m.msgSvrId ||
+          (m.talker && m.createdTimeMs ? `${m.talker}-${m.createdTimeMs}` : `msg-${emitted}`);
+        yield {
+          adapter: NAME,
+          kind: KIND_MESSAGE,
+          originalId: stableOriginalId(KIND_MESSAGE, idPart),
+          capturedAt,
+          payload: { kind: KIND_MESSAGE, ...m },
+        };
+        emitted += 1;
+      }
+    }
+
+    if (include[KIND_CONTACT] !== false) {
+      for (const c of contacts) {
+        if (emitted >= limit) return;
+        if (!c || typeof c !== "object" || !c.wxid) continue;
+        yield {
+          adapter: NAME,
+          kind: KIND_CONTACT,
+          originalId: stableOriginalId(KIND_CONTACT, c.wxid),
+          capturedAt: fallbackCapturedAt,
+          payload: { kind: KIND_CONTACT, ...c },
+        };
+        emitted += 1;
+      }
+    }
+  }
+
+  normalize(raw) {
+    if (!raw || !raw.payload) {
+      throw new Error("WeChatPcAdapter.normalize: payload missing");
+    }
+    const kind = raw.kind || raw.payload.kind;
+    const ingestedAt = Date.now();
+    if (kind === KIND_MESSAGE) return normalizeMessage(raw.payload, raw, ingestedAt);
+    if (kind === KIND_CONTACT) return normalizeContact(raw.payload, raw, ingestedAt);
+    throw new Error(`WeChatPcAdapter.normalize: unknown kind ${kind}`);
+  }
+}
+
+function buildSource(raw, occurredAt) {
+  return {
+    adapter: NAME,
+    adapterVersion: VERSION,
+    originalId: raw.originalId,
+    capturedAt: raw.capturedAt || occurredAt,
+    capturedBy: CAPTURED_BY.SQLITE,
+  };
+}
+
+function normalizeMessage(p, raw, ingestedAt) {
+  const occurredAt =
+    (typeof p.createdTimeMs === "number" && p.createdTimeMs) || raw.capturedAt || ingestedAt;
+  const source = buildSource(raw, occurredAt);
+  const text = typeof p.text === "string" ? p.text : "";
+  const isSend = Number(p.isSend) === 1;
+  const isGroup = !!p.isGroup;
+  // actor: outbound = self; inbound 1-on-1 = talker; group = sender prefix.
+  const selfId = "person-wechat-self";
+  let actor;
+  if (isGroup) {
+    actor = p.senderWxid ? wxidToPersonId(p.senderWxid) : selfId;
+  } else {
+    actor = isSend ? selfId : (p.talker ? wxidToPersonId(p.talker) : selfId);
+  }
+
+  const persons = [];
+  if (!isGroup && p.talker && !p.talker.endsWith("@chatroom")) {
+    persons.push({
+      id: wxidToPersonId(p.talker),
+      type: ENTITY_TYPES.PERSON,
+      subtype: PERSON_SUBTYPES.CONTACT,
+      names: [p.talker],
+      ingestedAt,
+      source,
+      identifiers: { wechatId: p.talker },
+      extra: { platform: "wechat", source: "pc", wxid: p.talker },
+    });
+  }
+  if (isGroup && p.senderWxid) {
+    persons.push({
+      id: wxidToPersonId(p.senderWxid),
+      type: ENTITY_TYPES.PERSON,
+      subtype: PERSON_SUBTYPES.CONTACT,
+      names: [p.senderWxid],
+      ingestedAt,
+      source,
+      identifiers: { wechatId: p.senderWxid },
+      extra: { platform: "wechat", source: "pc", wxid: p.senderWxid },
+    });
+  }
+
+  const topics = [];
+  if (isGroup && p.talker) {
+    topics.push({
+      id: `topic-wechat-group-${p.talker}`,
+      type: ENTITY_TYPES.TOPIC,
+      name: p.talker.replace("@chatroom", ""),
+      ingestedAt,
+      source,
+      extra: { platform: "wechat", source: "pc", wxid: p.talker },
+    });
+  }
+
+  return {
+    events: [{
+      id: newId(),
+      type: ENTITY_TYPES.EVENT,
+      subtype: EVENT_SUBTYPES.MESSAGE,
+      occurredAt,
+      actor: actor || selfId,
+      content: {
+        title: text ? text.slice(0, 80) : "(非文本消息)",
+        text,
+      },
+      ingestedAt,
+      source,
+      extra: {
+        platform: "wechat",
+        source: "pc",
+        talker: p.talker || null,
+        isSend,
+        isGroup,
+        wechatType: typeof p.type === "number" ? p.type : null,
+        senderWxid: p.senderWxid || null,
+        contentBlob: typeof p.contentBlob === "string" ? p.contentBlob : null,
+        ...(topics.length ? { topicId: topics[0].id } : {}),
+      },
+    }],
+    persons,
+    places: [],
+    items: [],
+    topics,
+  };
+}
+
+function normalizeContact(p, raw, ingestedAt) {
+  const wxid = p.wxid ? String(p.wxid) : null;
+  const occurredAt = raw.capturedAt || ingestedAt;
+  const source = buildSource(raw, occurredAt);
+  const names = [p.remark, p.nickname, p.alias, wxid].filter(
+    (n) => typeof n === "string" && n.length > 0,
+  );
+  const subtype =
+    wxid && wxid.startsWith("gh_") ? PERSON_SUBTYPES.MERCHANT : PERSON_SUBTYPES.CONTACT;
+  return {
+    events: [],
+    persons: [{
+      id: wxidToPersonId(wxid) || `person-wechat-${newId()}`,
+      type: ENTITY_TYPES.PERSON,
+      subtype,
+      names: names.length ? names : ["(unnamed)"],
+      ingestedAt,
+      source,
+      identifiers: wxid ? { wechatId: wxid } : {},
+      extra: {
+        platform: "wechat",
+        source: "pc",
+        wxid,
+        alias: p.alias || null,
+        wechatType: typeof p.type === "number" ? p.type : null,
+      },
+    }],
+    places: [],
+    items: [],
+    topics: [],
+  };
+}
+
+module.exports = {
+  WeChatPcAdapter,
+  NAME,
+  VERSION,
+  wxidToPersonId,
+};

package/lib/adapters/wechat-pc/pc-db-reader.js

@@ -0,0 +1,327 @@
+"use strict";
+
+/**
+ * WeChat **desktop (PC)** local-DB direct reader — 本地直读样板, ported from
+ * the Douyin im.db sample (social-douyin-adb/im-db-parser.js) to PC WeChat.
+ *
+ * KEY DIFFERENCE from the Android `wechat/` adapter:
+ *   - Android WeChat: ONE EnMicroMsg.db, tables `message` / `rcontact` /
+ *     `chatroom`, key = MD5(IMEI+UIN) or frida.
+ *   - PC WeChat 3.x: messages live in `MSG0.db`..`MSGN.db` (table `MSG`),
+ *     contacts + groups live in `MicroMsg.db` (tables `Contact` / `ChatRoom`).
+ *     Encrypted with SQLCipher using a 32-byte (64-hex) raw key extracted
+ *     from the running WeChat.exe process memory.
+ *
+ * Two ways in (mirrors the user's "愿意本地解密" stance):
+ *
+ *   1. PLAINTEXT (recommended, fully reliable + testable): the user decrypts
+ *      the PC DB to a plain SQLite file first (PyWxDump / 手动 SQLCipher
+ *      decrypt) and points the adapter at it. WeChat PC's SQLCipher uses a
+ *      non-standard per-page HMAC salt scheme, so "decrypt-to-plaintext
+ *      then read" is the proven path — same shape as the Douyin plaintext
+ *      im.db sample.
+ *
+ *   2. ENCRYPTED + raw key (best-effort): if a 64-hex key is supplied we try
+ *      the documented PC SQLCipher PRAGMA profile. Some WeChat builds open
+ *      cleanly this way; if not, fall back to method 1.
+ *
+ * This reader does NOT extract the key (that needs OS-specific process-memory
+ * scanning — out of scope here; the guide points at the manual step). It
+ * opens what it's given and reads whatever of {MSG, Contact, ChatRoom} the
+ * file contains, so the SAME reader serves both MSG*.db (messages) and
+ * MicroMsg.db (contacts) — point it at each in turn.
+ *
+ * Test seam: inject a synthetic `_databaseClass` to bypass the native
+ * dual-load (mirrors douyin im-db-parser + bilibili chromium-cookies-reader).
+ */
+
+// PC WeChat 3.x SQLCipher params (documented by PyWxDump et al.). Applied
+// only when a raw key is supplied. cipher_compatibility 3 ≈ WeChat's
+// page_size 4096 / kdf_iter 64000 / HMAC-SHA1 layout. Tried in order.
+const KNOWN_PC_PRAGMA_PROFILES = Object.freeze([
+  {
+    name: "wechat-pc-v3",
+    pragmas: [
+      "PRAGMA cipher_compatibility = 3",
+      "PRAGMA cipher_page_size = 4096",
+      "PRAGMA kdf_iter = 64000",
+      "PRAGMA cipher_hmac_algorithm = HMAC_SHA1",
+      "PRAGMA cipher_kdf_algorithm = PBKDF2_HMAC_SHA1",
+    ],
+  },
+  {
+    name: "wechat-pc-v4",
+    pragmas: [
+      "PRAGMA cipher_compatibility = 4",
+      "PRAGMA cipher_page_size = 4096",
+    ],
+  },
+]);
+
+function loadDatabaseClass() {
+  for (const mod of ["better-sqlite3-multiple-ciphers", "better-sqlite3"]) {
+    let cls;
+    try {
+      // eslint-disable-next-line global-require
+      cls = require(mod);
+    } catch (_e) {
+      continue;
+    }
+    try {
+      const probe = new cls(":memory:");
+      probe.close();
+      return cls;
+    } catch (_e) {
+      // ABI mismatch — try next
+    }
+  }
+  throw new Error(
+    "wechat-pc-db-reader: neither better-sqlite3-multiple-ciphers nor better-sqlite3 loaded — both ABI-mismatched",
+  );
+}
+
+function trySelect(db, sql) {
+  try {
+    return db.prepare(sql).all();
+  } catch (_e) {
+    return null;
+  }
+}
+
+function pickCol(columns, candidates) {
+  for (const c of candidates) {
+    if (columns.has(c)) return c;
+  }
+  return null;
+}
+
+/**
+ * Normalize PC WeChat timestamps to ms. PC stores CreateTime in SECONDS
+ * (10-digit). Be defensive about ms/µs the same way Douyin is.
+ */
+function normalizeEpochMs(v) {
+  if (typeof v !== "number" || !Number.isFinite(v) || v <= 0) return null;
+  if (v > 1e15) return Math.floor(v / 1000); // µs
+  if (v > 1e12) return Math.floor(v); // ms
+  return Math.floor(v * 1000); // seconds
+}
+
+/**
+ * For Type=1 (plain text) messages StrContent IS the text. For group
+ * messages PC prefixes the sender wxid + ":\n" inside StrContent; strip it
+ * so the text is clean and expose the sender separately.
+ */
+function parsePcContent(strContent, isGroup) {
+  if (typeof strContent !== "string" || strContent.length === 0) {
+    return { text: "", senderWxid: null };
+  }
+  if (isGroup) {
+    const idx = strContent.indexOf(":\n");
+    if (idx > 0 && idx < 80) {
+      return {
+        senderWxid: strContent.slice(0, idx),
+        text: strContent.slice(idx + 2),
+      };
+    }
+  }
+  return { text: strContent, senderWxid: null };
+}
+
+function isGroupTalker(talker) {
+  return typeof talker === "string" && talker.endsWith("@chatroom");
+}
+
+/**
+ * Open a PC WeChat DB (encrypted-with-key OR already-plaintext).
+ *
+ * @param {string} dbPath
+ * @param {{ key?: string, _databaseClass?: any }} [opts]
+ * @returns {{ db: object, mode: "plaintext"|"sqlcipher", profile: string|null }}
+ */
+function openPcWeChatDb(dbPath, opts = {}) {
+  const Database = opts._databaseClass || loadDatabaseClass();
+  const key = typeof opts.key === "string" && opts.key.length > 0 ? opts.key : null;
+
+  if (!key) {
+    // Plaintext path — already-decrypted db. Probe sqlite_master.
+    const db = new Database(dbPath, { readonly: true });
+    try {
+      db.prepare("SELECT count(*) AS n FROM sqlite_master").get();
+      return { db, mode: "plaintext", profile: null };
+    } catch (err) {
+      try { db.close(); } catch (_e) { /* ignore */ }
+      const e = new Error(
+        `wechat-pc-db-reader: db is not plaintext SQLite (supply a 64-hex key, or decrypt first): ${err.message}`,
+      );
+      e.code = "WECHAT_PC_NEEDS_KEY";
+      throw e;
+    }
+  }
+
+  // SQLCipher path — raw hex key. Try each known PC profile.
+  const keyExpr = /^[0-9a-fA-F]{64}$/.test(key) ? `"x'${key}'"` : `'${key}'`;
+  let lastError = null;
+  for (const profile of KNOWN_PC_PRAGMA_PROFILES) {
+    let db;
+    try {
+      db = new Database(dbPath, { readonly: true });
+      db.pragma(`key = ${keyExpr}`);
+      for (const p of profile.pragmas) db.exec(p);
+      const row = db.prepare("SELECT count(*) AS n FROM sqlite_master").get();
+      if (row && Number.isFinite(row.n)) {
+        return { db, mode: "sqlcipher", profile: profile.name };
+      }
+      db.close();
+    } catch (err) {
+      lastError = err;
+      if (db) {
+        try { db.close(); } catch (_e) { /* ignore */ }
+      }
+    }
+  }
+  const e = new Error(
+    `wechat-pc-db-reader: failed to open with any SQLCipher profile — ` +
+      `key wrong, or WeChat build needs decrypt-to-plaintext first. ` +
+      `Last error: ${lastError && lastError.message}`,
+  );
+  e.code = "WECHAT_PC_DECRYPT_FAILED";
+  throw e;
+}
+
+/**
+ * Read messages + contacts out of a PC WeChat DB. Reads whatever of
+ * {MSG, Contact} the file contains (MSG*.db has MSG; MicroMsg.db has
+ * Contact), so the same call works for either file.
+ *
+ * Returns `{ messages, contacts, diagnostic }`:
+ *   messages: {msgSvrId, talker, isSend, createdTimeMs, type, text,
+ *              senderWxid, isGroup, contentBlob}
+ *   contacts: {wxid, alias, nickname, remark, type}
+ *   diagnostic: {messageCount, contactCount, hadMsgTable, hadContactTable,
+ *                mode, profile}
+ *
+ * @param {string} dbPath
+ * @param {{key?, _databaseClass?, limitMessages?, limitContacts?}} [opts]
+ */
+function readPcWeChat(dbPath, opts = {}) {
+  if (typeof dbPath !== "string" || dbPath.length === 0) {
+    throw new TypeError("readPcWeChat: dbPath must be a non-empty string");
+  }
+  const limitMessages =
+    Number.isInteger(opts.limitMessages) && opts.limitMessages > 0
+      ? opts.limitMessages
+      : 20_000;
+  const limitContacts =
+    Number.isInteger(opts.limitContacts) && opts.limitContacts > 0
+      ? opts.limitContacts
+      : 10_000;
+
+  const { db, mode, profile } = openPcWeChatDb(dbPath, opts);
+  const out = {
+    messages: [],
+    contacts: [],
+    diagnostic: {
+      messageCount: 0,
+      contactCount: 0,
+      hadMsgTable: false,
+      hadContactTable: false,
+      mode,
+      profile,
+    },
+  };
+  try {
+    // ─── MSG table (messages) ────────────────────────────────────────────
+    const msgInfo = trySelect(db, "PRAGMA table_info(MSG)");
+    if (Array.isArray(msgInfo) && msgInfo.length > 0) {
+      out.diagnostic.hadMsgTable = true;
+      const cols = new Set(msgInfo.map((r) => r.name));
+      const svrCol = pickCol(cols, ["MsgSvrID", "msgSvrId", "MsgSvrId"]);
+      const talkerCol = pickCol(cols, ["StrTalker", "strTalker", "Talker", "talker"]);
+      const sendCol = pickCol(cols, ["IsSender", "isSend", "IsSend"]);
+      const timeCol = pickCol(cols, ["CreateTime", "createTime", "create_time"]);
+      const typeCol = pickCol(cols, ["Type", "type", "MsgType"]);
+      const contentCol = pickCol(cols, ["StrContent", "strContent", "Content", "content"]);
+      const localIdCol = pickCol(cols, ["localId", "MsgId", "msgId"]);
+      if (timeCol && contentCol) {
+        const fields = [];
+        if (svrCol) fields.push(`${svrCol} AS msgSvrId`);
+        if (localIdCol) fields.push(`${localIdCol} AS localId`);
+        if (talkerCol) fields.push(`${talkerCol} AS talker`);
+        if (sendCol) fields.push(`${sendCol} AS isSend`);
+        if (typeCol) fields.push(`${typeCol} AS type`);
+        fields.push(`${timeCol} AS createTime`);
+        fields.push(`${contentCol} AS content`);
+        const sql =
+          `SELECT ${fields.join(", ")} FROM MSG ORDER BY ${timeCol} DESC LIMIT ${limitMessages}`;
+        const rows = trySelect(db, sql) || [];
+        for (const r of rows) {
+          const isGroup = isGroupTalker(r.talker);
+          const { text, senderWxid } = parsePcContent(r.content, isGroup);
+          out.messages.push({
+            msgSvrId: r.msgSvrId != null ? String(r.msgSvrId) : (r.localId != null ? `local-${r.localId}` : null),
+            talker: r.talker ? String(r.talker) : null,
+            isSend: typeof r.isSend === "number" ? r.isSend : null,
+            createdTimeMs: normalizeEpochMs(r.createTime),
+            type: typeof r.type === "number" ? r.type : null,
+            text,
+            senderWxid,
+            isGroup,
+            contentBlob: typeof r.content === "string" ? r.content : null,
+          });
+        }
+        out.diagnostic.messageCount = out.messages.length;
+      }
+    }
+
+    // ─── Contact table (contacts) ────────────────────────────────────────
+    const contactInfo = trySelect(db, "PRAGMA table_info(Contact)");
+    if (Array.isArray(contactInfo) && contactInfo.length > 0) {
+      out.diagnostic.hadContactTable = true;
+      const cols = new Set(contactInfo.map((r) => r.name));
+      const wxidCol = pickCol(cols, ["UserName", "userName", "Username", "username"]);
+      const aliasCol = pickCol(cols, ["Alias", "alias"]);
+      const nickCol = pickCol(cols, ["NickName", "nickName", "nickname"]);
+      const remarkCol = pickCol(cols, ["Remark", "remark", "ConRemark", "conRemark"]);
+      const typeCol = pickCol(cols, ["Type", "type"]);
+      if (wxidCol) {
+        const fields = [`${wxidCol} AS wxid`];
+        if (aliasCol) fields.push(`${aliasCol} AS alias`);
+        if (nickCol) fields.push(`${nickCol} AS nickname`);
+        if (remarkCol) fields.push(`${remarkCol} AS remark`);
+        if (typeCol) fields.push(`${typeCol} AS type`);
+        const sql = `SELECT ${fields.join(", ")} FROM Contact LIMIT ${limitContacts}`;
+        const rows = trySelect(db, sql) || [];
+        for (const r of rows) {
+          if (!r.wxid) continue;
+          const wxid = String(r.wxid);
+          // Skip WeChat internal placeholders + chatrooms (not Persons).
+          if (wxid.endsWith("@chatroom")) continue;
+          out.contacts.push({
+            wxid,
+            alias: r.alias || null,
+            nickname: r.nickname || null,
+            remark: r.remark || null,
+            type: typeof r.type === "number" ? r.type : null,
+          });
+        }
+        out.diagnostic.contactCount = out.contacts.length;
+      }
+    }
+  } finally {
+    try { db.close(); } catch (_e) { /* ignore */ }
+  }
+  return out;
+}
+
+module.exports = {
+  readPcWeChat,
+  openPcWeChatDb,
+  KNOWN_PC_PRAGMA_PROFILES,
+  _internals: {
+    loadDatabaseClass,
+    normalizeEpochMs,
+    parsePcContent,
+    isGroupTalker,
+    pickCol,
+  },
+};