@chainlesschain/personal-data-hub 0.4.2 → 0.4.3

package/__tests__/adapters/qq-pc-direct-read.test.js

@@ -189,3 +189,39 @@ describe("QQPcAdapter — edge cases", () => {
     expect(() => a.normalize({ kind: "x", payload: { kind: "x" } })).toThrow(/unknown kind/);
   });
 });
+
+describe("QQPcAdapter — QQ NT sidecar path (passphrase)", () => {
+  const fakeCollector = (result) => async (_opts) => result;
+
+  it("opts.passphrase routes through the sidecar collector and yields messages", async () => {
+    const a = new QQPcAdapter({
+      qqCollector: fakeCollector({
+        account: "896075341",
+        messageCount: 2,
+        c2c: 1,
+        group: 1,
+        messages: [
+          { kind: "group", peer: 88966001, peerUid: "u_x", senderUin: 38181604, senderName: "疯子", type: 0, createTime: 1780941580, text: "保持高贵的沉默。", originalId: "qq-pc:group:88966001:1" },
+          { kind: "c2c", peer: 2747277822, peerUid: "u_y", senderUin: 12345, senderName: "张三", type: 0, createTime: 1780900000, text: "在吗", originalId: "qq-pc:c2c:2747277822:2" },
+        ],
+      }),
+    });
+    const raws = await collect(a.sync({ passphrase: "5{sww#,6aq=)8=A@" }));
+    expect(raws).toHaveLength(2);
+    expect(raws[0].payload.text).toBe("保持高贵的沉默。");
+    expect(raws[0].payload.isGroup).toBe(true);
+    expect(raws[0].payload.senderName).toBe("疯子");
+    expect(raws[1].payload.isGroup).toBe(false);
+
+    const merged = { events: [], persons: [], places: [], items: [], topics: [] };
+    for (const r of raws) {
+      const n = a.normalize(r);
+      for (const k of Object.keys(merged)) if (Array.isArray(n[k])) merged[k].push(...n[k]);
+    }
+    const { valid } = partitionBatch(merged);
+    expect(valid.events.length).toBe(2);
+    const texts = valid.events.map((e) => e.content && e.content.text);
+    expect(texts).toContain("保持高贵的沉默。");
+    expect(valid.events.find((e) => e.content.text === "保持高贵的沉默。").extra.senderName).toBe("疯子");
+  });
+});

package/lib/adapter-guide.js

@@ -346,22 +346,24 @@ const ADAPTER_OVERRIDES = Object.freeze({
 
   "qq-pc": {
     summary:
-      "采集电脑版 QQ（NT 新版）的聊天记录（来自本地 nt_msg.db）。⚠️ v0.1 实验性：QQ NT 用数字化列名 + protobuf 消息体且 schema 随版本变化，文本解析为尽力而为，原始行会完整保留以便后续解析。",
+      "采集电脑版 QQ（NT 新版）的聊天记录（来自本地 nt_msg.db）。中台已支持自动解密 + 解析：取一次密钥后，自动解密 SQLCipher 库、解析 c2c/群消息的 protobuf 正文为可读文本（含发送者昵称、群号）。",
     methods: [
       {
-        label: "方式一：解密 nt_msg.db 后本地直读（推荐）",
+        label: "方式一：取密钥后一键采集（推荐）",
         recommended: true,
         steps: [
-          "登录电脑版 QQ，定位数据目录（默认 文档\\Tencent Files 或 %APPDATA%\\Tencent\\QQ\\nt_qq_*\\nt_db\\）。",
-          "用工具（如 QQNTDecrypt / PyQQ 等）解密 nt_msg.db 为明文 SQLite。",
-          "执行 `cc hub sync-adapter qq-pc --input <解密后的 nt_msg.db>`。",
-          "中台读取 c2c_msg_table / group_msg_table 入库（文本尽力解析，原始数据保留）。",
+          "在电脑上打开并登录 QQ（NT 新版，数据在 文档\\Tencent Files\\<QQ号>\\nt_qq\\nt_db\\nt_msg.db）。",
+          "下载并运行 qq-win-db-key（github.com/QQBackup/qq-win-db-key 的 windows_ntqq_get_key.ps1）。它会全关 QQ → 以调试器启动 QQ → 你登录后自动抓出 16 位密钥（形如 5{sww#,6aq=)8=A@）。",
+          "回到中台执行 `cc hub sync-adapter qq-pc --passphrase \"<那串密钥>\"`（或点该行「一键采集」并粘贴密钥）。",
+          "中台自动解密 + 解析 c2c_msg_table / group_msg_table → 可读消息入库（私聊 + 群聊，含昵称/群号）。",
         ],
-        note: "QQ NT 消息正文为 protobuf BLOB，部分类型文本可能需后续在真机上微调列/解码。诊断会显示找到了哪些表/列。",
+        note: "QQ 每次重启密钥会变，重采时重新跑 qq-win-db-key 取一次即可。纯个人使用、全程本地；首次会要求法律确认。依赖随中台分发的 Python（含 cryptography）。",
       },
       {
-        label: "方式二：提供密钥让中台尝试直接解密（试验性）",
-        steps: ["附带 `--key <hex>`，中台用 SQLCipher 尝试打开；失败则回退方式一。"],
+        label: "方式二：已解密为明文库则直接导入",
+        steps: [
+          "若已用工具把 nt_msg.db 解密为明文 SQLite，执行 `cc hub sync-adapter qq-pc --input <明文 nt_msg.db>`。",
+        ],
       },
     ],
   },

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

@@ -37,6 +37,9 @@ class QQPcAdapter {
   constructor(opts = {}) {
     this._dbPath = opts.dbPath || null;
     this._key = opts.key || null;
+    // QQ NT passphrase (16-char ASCII from qq-win-db-key). When present, sync
+    // routes through the Python sidecar (decrypt + protobuf parse).
+    this._passphrase = opts.passphrase || null;
 
     this.name = NAME;
     this.version = VERSION;
@@ -58,6 +61,10 @@ class QQPcAdapter {
     this._deps = {
       fs,
       dbDriverFactory: opts.dbDriverFactory || null,
+      // DI seam: tests inject a fake QQ sidecar collector; default lazy-loads
+      // the forensics-bridge invoker.
+      qqCollector: opts.qqCollector || null,
+      discoveryDeps: opts.discoveryDeps || undefined,
     };
   }
 
@@ -134,10 +141,18 @@ class QQPcAdapter {
   }
 
   async *sync(opts = {}) {
+    // Sidecar path: with a QQ NT passphrase (from qq-win-db-key), decrypt +
+    // parse the encrypted nt_msg.db in Python and yield readable messages.
+    const passphrase = opts.passphrase || this._passphrase || null;
+    if (passphrase || opts.mode === "sidecar") {
+      yield* this._syncViaSidecar(opts, passphrase);
+      return;
+    }
+
     const dbPath =
       opts.dbPath || opts.inputPath || this._dbPath || this._resolveDiscoveredDbPath();
     if (!dbPath) {
-      throw new Error("qq-pc.sync: 未找到本机 QQ NT 库且未提供 opts.dbPath / opts.inputPath");
+      throw new Error("qq-pc.sync: 未找到本机 QQ NT 库且未提供 opts.dbPath / opts.inputPath（或提供 opts.passphrase 走 sidecar 解密）");
     }
     if (!this._deps.fs.existsSync(dbPath)) return;
 
@@ -178,6 +193,60 @@ class QQPcAdapter {
     }
   }
 
+  // Sidecar path: forensics-bridge qq_nt.collect decrypts nt_msg.db (with the
+  // qq-win-db-key passphrase) + parses c2c/group protobuf bodies → readable
+  // messages, which we map into the same payload normalizeMessage consumes.
+  async *_syncViaSidecar(opts = {}, passphrase) {
+    let collect = this._deps.qqCollector;
+    if (!collect) {
+      // eslint-disable-next-line global-require
+      collect = require("./qqnt-sidecar").collectQqNt;
+    }
+    const limit = Number.isInteger(opts.limit) && opts.limit > 0 ? opts.limit : undefined;
+    const result = await collect({
+      passphrase,
+      key: opts.key || this._key || undefined,
+      dbPath: opts.dbPath || this._dbPath || this._resolveDiscoveredDbPath() || undefined,
+      limit,
+      pythonExe: opts.pythonExe,
+      bridgeDir: opts.bridgeDir,
+      timeoutMs: opts.timeoutMs,
+      onProgress:
+        typeof opts.onProgress === "function"
+          ? (m) => { try { opts.onProgress({ phase: "qq-nt", adapter: NAME, ...m }); } catch (_e) { /* best-effort */ } }
+          : undefined,
+      _supervisorFactory: opts._supervisorFactory,
+    });
+    const messages = (result && Array.isArray(result.messages)) ? result.messages : [];
+    const fallbackCapturedAt = Date.now();
+    let emitted = 0;
+    for (const m of messages) {
+      if (!m || typeof m !== "object") continue;
+      const isGroup = m.kind === "group";
+      const createdTimeMs =
+        typeof m.createTime === "number" && m.createTime > 0 ? m.createTime * 1000 : null;
+      const payload = {
+        kind: KIND_MESSAGE,
+        text: typeof m.text === "string" ? m.text : "",
+        peerUin: m.peer != null ? String(m.peer) : null,
+        peerName: m.conversationName || null,   // group name / c2c peer nickname (best-effort)
+        senderUin: m.senderUin != null ? String(m.senderUin) : null,
+        senderName: m.senderName || null,
+        isGroup,
+        type: typeof m.type === "number" ? m.type : null,
+        createdTimeMs,
+      };
+      yield {
+        adapter: NAME,
+        kind: KIND_MESSAGE,
+        originalId: m.originalId || stableOriginalId(`${m.peer}-${createdTimeMs}-${emitted}`),
+        capturedAt: createdTimeMs || fallbackCapturedAt,
+        payload,
+      };
+      emitted += 1;
+    }
+  }
+
   normalize(raw) {
     if (!raw || !raw.payload) {
       throw new Error("QQPcAdapter.normalize: payload missing");
@@ -215,7 +284,9 @@ class QQPcAdapter {
           platform: "qq",
           source: "pc-nt",
           peerUin: p.peerUin || null,
+          ...(p.peerName ? { peerName: p.peerName } : {}),
           senderUin: p.senderUin || null,
+          ...(p.senderName ? { senderName: p.senderName } : {}),
           isGroup: !!p.isGroup,
           qqMsgType: typeof p.type === "number" ? p.type : null,
           // Full raw row preserved — protobuf bodies + unknown columns — so a

package/lib/adapters/qq-pc/qqnt-sidecar.js

@@ -0,0 +1,109 @@
+"use strict";
+
+/**
+ * QQ NT collection bridge — invokes the forensics-bridge Python sidecar's
+ * `qq_nt.collect` method (skip 1024-byte preamble + SQLCipher-4 decrypt with
+ * the qq-win-db-key passphrase + parse c2c/group protobuf message bodies) and
+ * returns the decrypted, readable messages to the node adapter.
+ *
+ * The key is the QQ NT passphrase (a 16-char ASCII string like "5{sww#,6aq=)8=A@"
+ * extracted by qq-win-db-key). Pass it as opts.passphrase. Decryption + protobuf
+ * text extraction run in Python (cryptography), sidestepping the host-node
+ * bs3mc ABI problem (node never opens the encrypted DB).
+ *
+ * Resolution (overridable for tests / packaging):
+ *   - python exe:  opts.pythonExe → env CC_PDH_PYTHON → "python" / "python3"
+ *   - bridge dir:  opts.bridgeDir → env CC_PDH_BRIDGE_DIR → sibling package
+ */
+
+const path = require("node:path");
+const { existsSync } = require("node:fs");
+
+function resolveBridgeDir(explicit) {
+  if (explicit) return explicit;
+  if (process.env.CC_PDH_BRIDGE_DIR) return process.env.CC_PDH_BRIDGE_DIR;
+  // lib/adapters/qq-pc → up to packages/, then sibling bridge package.
+  return path.resolve(__dirname, "../../../../personal-data-hub-bridge");
+}
+
+function pythonCandidates(explicit) {
+  const list = [];
+  if (explicit) list.push(explicit);
+  if (process.env.CC_PDH_PYTHON) list.push(process.env.CC_PDH_PYTHON);
+  list.push(process.platform === "win32" ? "python" : "python3");
+  list.push(process.platform === "win32" ? "python3" : "python");
+  return [...new Set(list)];
+}
+
+/**
+ * @param {object} [opts]
+ * @param {string} [opts.passphrase]  QQ NT key (ASCII passphrase from qq-win-db-key)
+ * @param {string} [opts.key]         alternatively a hex key
+ * @param {string} [opts.dbPath]      nt_msg.db path (sidecar auto-discovers if omitted)
+ * @param {number} [opts.limit]
+ * @param {string} [opts.pythonExe]
+ * @param {string} [opts.bridgeDir]
+ * @param {number} [opts.timeoutMs]
+ * @param {(msg:object)=>void} [opts.onProgress]
+ * @param {object} [opts._supervisorFactory]  test seam
+ * @returns {Promise<{account:string,messageCount:number,c2c:number,group:number,messages:object[]}>}
+ */
+async function collectQqNt(opts = {}) {
+  const bridgeDir = resolveBridgeDir(opts.bridgeDir);
+  const makeSupervisor =
+    opts._supervisorFactory ||
+    ((command, cwd) => {
+      // eslint-disable-next-line global-require
+      const { SidecarSupervisor } = require("../../sidecar");
+      return new SidecarSupervisor({
+        command,
+        cwd,
+        defaultTimeoutMs: opts.timeoutMs || 120_000,
+        healthCheckIntervalMs: 0,
+      });
+    });
+
+  if (!opts._supervisorFactory && !existsSync(bridgeDir)) {
+    const e = new Error(
+      `qq-pc: forensics-bridge not found at ${bridgeDir} (set CC_PDH_BRIDGE_DIR)`,
+    );
+    e.code = "BRIDGE_NOT_FOUND";
+    throw e;
+  }
+
+  const params = {};
+  if (Number.isInteger(opts.limit) && opts.limit > 0) params.limit = opts.limit;
+  if (opts.passphrase) params.passphrase = opts.passphrase;
+  else if (opts.key) params.key = opts.key;
+  if (opts.dbPath) params.db_path = opts.dbPath;
+
+  let lastErr = null;
+  for (const py of pythonCandidates(opts.pythonExe)) {
+    const sup = makeSupervisor([py, "-m", "forensics_bridge.ipc_server"], bridgeDir);
+    try {
+      await sup.start({ readyTimeoutMs: opts.readyTimeoutMs || 15_000 });
+      const result = await sup.invoke("qq_nt.collect", params, {
+        timeoutMs: opts.timeoutMs || 120_000,
+        onProgress: opts.onProgress,
+      });
+      try { await sup.stop(); } catch (_e) { /* best-effort */ }
+      return result;
+    } catch (err) {
+      lastErr = err;
+      try { await sup.stop(); } catch (_e) { /* best-effort */ }
+      const msg = (err && err.message) || "";
+      // Real QQ-side failures (key/db) surface immediately; sidecar-availability
+      // problems (missing python / cryptography / spawn death) → try next python.
+      const isDataError = /KEY_REQUIRED|KEY_VERIFY|APP_NOT|DB_TOO|BAD_LAYOUT/i.test(msg);
+      if (isDataError) throw err;
+    }
+  }
+  const e = new Error(
+    `qq-pc: could not run forensics-bridge sidecar (tried ${pythonCandidates(opts.pythonExe).join(", ")}). ` +
+      `Install Python 3.11+ with 'cryptography', or set CC_PDH_PYTHON. Last error: ${lastErr && lastErr.message}`,
+  );
+  e.code = "SIDECAR_UNAVAILABLE";
+  throw e;
+}
+
+module.exports = { collectQqNt, _internals: { resolveBridgeDir, pythonCandidates } };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chainlesschain/personal-data-hub",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "Personal Data Hub — UnifiedSchema + validators + KG ingest helpers for the data-back-to-the-individual middleware",
   "type": "commonjs",
   "main": "lib/index.js",