@chainlesschain/personal-data-hub 0.4.0 → 0.4.2

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

@@ -81,21 +81,52 @@ class WeChatPcAdapter {
       fs,
       // DI seam: tests inject a fake SQLite driver class via dbDriverFactory.
       dbDriverFactory: opts.dbDriverFactory || null,
+      // DI seam: tests inject a fake WeChat 4.x collector; default lazy-loads
+      // the forensics-bridge sidecar invoker.
+      v4Collector: opts.v4Collector || null,
+      // DI seam for discovery (see _autoDiscover).
+      discoveryDeps: opts.discoveryDeps || undefined,
     };
   }
 
+  // Auto-discover PC WeChat's local DB on the host (3.x + 4.x layouts) so the
+  // UI never needs a manually typed path. Lazy-required + cached per instance.
+  _autoDiscover() {
+    if (this._discovered !== undefined) return this._discovered;
+    try {
+      // eslint-disable-next-line global-require
+      const { discover } = require("../_pc-local-discovery");
+      this._discovered = discover("wechat-pc", this._deps.discoveryDeps || {});
+    } catch (_e) {
+      this._discovered = null;
+    }
+    return this._discovered;
+  }
+
   async authenticate(ctx = {}) {
     // Cheap readiness probe — never opens / decrypts a DB.
     if (ctx && ctx.readinessOnly) {
       if (this._dbPath) return { ok: true, mode: "configured" };
+      const disc = this._autoDiscover();
+      if (disc && disc.installed) {
+        return {
+          ok: false,
+          reason: "DB_FOUND_NEEDS_KEY",
+          message: `已找到本机微信库（${disc.layout || ""} ${disc.accounts.length} 个账号，主库 ${disc.primaryDb}）`,
+          discovered: disc,
+        };
+      }
       return {
         ok: false,
-        reason: "DB_NOT_PULLED",
-        message:
-          "wechat-pc: 需提供 PC 微信本地数据库路径（MSG*.db / MicroMsg.db），加密库需先解密或提供 key",
+        reason: "APP_NOT_INSTALLED",
+        message: (disc && disc.note) || "未检测到本机微信数据（可能未安装或未登录）",
       };
     }
-    const dbPath = (ctx && ctx.inputPath) || (ctx && ctx.dbPath) || this._dbPath;
+    const dbPath =
+      (ctx && ctx.inputPath) ||
+      (ctx && ctx.dbPath) ||
+      this._dbPath ||
+      this._resolveDiscoveredDbPath();
     if (dbPath) {
       try {
         this._deps.fs.accessSync(dbPath, this._deps.fs.constants.R_OK);
@@ -108,22 +139,54 @@ class WeChatPcAdapter {
       }
       return { ok: true, mode: "sqlite" };
     }
+    const disc = this._autoDiscover();
+    if (disc && disc.installed) {
+      return {
+        ok: false,
+        reason: "DB_FOUND_NEEDS_KEY",
+        message: `已找到本机微信库（主库 ${disc.primaryDb}），需解密密钥`,
+        discovered: disc,
+      };
+    }
     return {
       ok: false,
-      reason: "DB_NOT_PULLED",
-      message: "wechat-pc.authenticate: needs opts.dbPath / inputPath (MSG*.db or MicroMsg.db)",
+      reason: "APP_NOT_INSTALLED",
+      message: "wechat-pc.authenticate: 未检测到本机微信库，也未提供 dbPath / inputPath",
     };
   }
 
+  // Resolve the auto-discovered primary message DB path (null if none).
+  _resolveDiscoveredDbPath() {
+    const disc = this._autoDiscover();
+    return disc && disc.installed && disc.primaryDb ? disc.primaryDb : null;
+  }
+
   async healthCheck() {
     return { ok: true, lastChecked: Date.now() };
   }
 
   async *sync(opts = {}) {
-    const dbPath = opts.dbPath || opts.inputPath || this._dbPath;
+    // WeChat 4.x path: encrypted SQLCipher-4 DBs whose key lives in Weixin.exe
+    // memory. Route through the Python sidecar (memory key + decrypt + parse)
+    // and yield the decrypted messages. Triggered when the user gives no
+    // explicit plaintext path AND discovery sees the 4.x layout, or opts.mode.
+    const disc = this._autoDiscover();
+    const noExplicitPath = !opts.dbPath && !opts.inputPath && !this._dbPath;
+    const useV4 =
+      opts.mode === "v4" ||
+      (noExplicitPath && disc && disc.installed && disc.layout === "4.x");
+    if (useV4) {
+      yield* this._syncV4(opts, disc);
+      return;
+    }
+
+    // One-click: when no explicit path is given, fall back to the
+    // auto-discovered primary message DB on this host (3.x plaintext/keyed).
+    const dbPath =
+      opts.dbPath || opts.inputPath || this._dbPath || this._resolveDiscoveredDbPath();
     if (!dbPath) {
       throw new Error(
-        "wechat-pc.sync: needs opts.dbPath / opts.inputPath pointing to a PC WeChat DB (MSG*.db or MicroMsg.db)",
+        "wechat-pc.sync: 未找到本机微信库且未提供 opts.dbPath / opts.inputPath",
       );
     }
     if (!this._deps.fs.existsSync(dbPath)) return;
@@ -186,6 +249,114 @@ class WeChatPcAdapter {
     }
   }
 
+  // WeChat 4.x: invoke the sidecar collector, then re-shape each decrypted
+  // message into the SAME payload the 3.x normalizeMessage() understands, so
+  // both layouts share one normalization path.
+  async *_syncV4(opts = {}, disc) {
+    let collect = this._deps.v4Collector;
+    if (!collect) {
+      // eslint-disable-next-line global-require
+      collect = require("./v4-sidecar").collectWeChatV4;
+    }
+    const limit = Number.isInteger(opts.limit) && opts.limit > 0 ? opts.limit : undefined;
+    const result = await collect({
+      limit,
+      key: opts.key || this._key || undefined,
+      pythonExe: opts.pythonExe,
+      bridgeDir: opts.bridgeDir,
+      timeoutMs: opts.timeoutMs,
+      onProgress:
+        typeof opts.onProgress === "function"
+          ? (m) => {
+              try { opts.onProgress({ phase: "wechat-v4", adapter: NAME, ...m }); } catch (_e) { /* best-effort */ }
+            }
+          : undefined,
+      _supervisorFactory: opts._supervisorFactory,
+    });
+    if (typeof opts.onProgress === "function") {
+      try {
+        opts.onProgress({
+          phase: "wechat-v4-done",
+          adapter: NAME,
+          account: result && result.account,
+          messageCount: result && result.messageCount,
+          dbs: result && result.dbs,
+        });
+      } catch (_e) { /* best-effort */ }
+    }
+    const selfWxid =
+      (result && result.account) ||
+      (disc && disc.accounts && disc.accounts[0] && disc.accounts[0].id) ||
+      null;
+    const fallbackCapturedAt = Date.now();
+    const messages = (result && Array.isArray(result.messages)) ? result.messages : [];
+    let emitted = 0;
+    // The sidecar already applied `limit` across all sources (chat/biz/sns/
+    // favorite). Yield everything it returned — do NOT re-cap here, or the
+    // trailing 朋友圈/收藏 entries and the contacts block would be skipped.
+    for (const m of messages) {
+      if (!m || typeof m !== "object") continue;
+      const conv = typeof m.conversation === "string" ? m.conversation : null;
+      const isGroup = !!conv && conv.endsWith("@chatroom");
+      const createdTimeMs =
+        typeof m.createTime === "number" && m.createTime > 0 ? m.createTime * 1000 : null;
+      // Map → 3.x payload shape consumed by normalizeMessage().
+      const payload = {
+        kind: KIND_MESSAGE,
+        msgSvrId: m.originalId || null,
+        talker: conv,
+        isSend: selfWxid && m.sender && m.sender === selfWxid ? 1 : 0,
+        type: typeof m.type === "number" ? m.type : null,
+        createdTimeMs,
+        text: typeof m.text === "string" ? m.text : "",
+        senderWxid: isGroup ? (m.sender || null) : null,
+        isGroup,
+        contentBlob: typeof m.text === "string" ? m.text : null,
+        // provenance: chat | biz(公众号) | sns(朋友圈) | favorite(收藏)
+        wechatSource: typeof m.source === "string" ? m.source : "chat",
+        appType: typeof m.appType === "number" ? m.appType : null,  // appmsg subtype (type 49)
+        appUrl: typeof m.appUrl === "string" ? m.appUrl : null,     // link/article url
+      };
+      const idPart =
+        m.originalId ||
+        (conv && createdTimeMs ? `${conv}-${createdTimeMs}` : `v4-${emitted}`);
+      yield {
+        adapter: NAME,
+        kind: KIND_MESSAGE,
+        originalId: m.originalId || stableOriginalId(KIND_MESSAGE, idPart),
+        capturedAt: createdTimeMs || fallbackCapturedAt,
+        payload,
+      };
+      emitted += 1;
+    }
+
+    // Contacts (from contact.db) → Person entities. Not bound by the message
+    // `limit` (that caps messages, not the address book). Opt out via
+    // opts.include.contact === false.
+    const include = opts.include || {};
+    if (include[KIND_CONTACT] !== false) {
+      const contacts = (result && Array.isArray(result.contacts)) ? result.contacts : [];
+      for (const c of contacts) {
+        if (!c || typeof c !== "object" || !c.wxid) continue;
+        if (typeof c.wxid === "string" && c.wxid.endsWith("@chatroom")) continue;
+        yield {
+          adapter: NAME,
+          kind: KIND_CONTACT,
+          originalId: stableOriginalId(KIND_CONTACT, c.wxid),
+          capturedAt: fallbackCapturedAt,
+          payload: {
+            kind: KIND_CONTACT,
+            wxid: c.wxid,
+            alias: c.alias || null,
+            nickname: c.nickname || null,
+            remark: c.remark || null,
+            type: typeof c.type === "number" ? c.type : null,
+          },
+        };
+      }
+    }
+  }
+
   normalize(raw) {
     if (!raw || !raw.payload) {
       throw new Error("WeChatPcAdapter.normalize: payload missing");
@@ -282,6 +453,9 @@ function normalizeMessage(p, raw, ingestedAt) {
         isSend,
         isGroup,
         wechatType: typeof p.type === "number" ? p.type : null,
+        wechatSource: typeof p.wechatSource === "string" ? p.wechatSource : "chat",
+        ...(p.appType != null ? { wechatAppType: p.appType } : {}),
+        ...(p.appUrl ? { url: p.appUrl } : {}),
         senderWxid: p.senderWxid || null,
         contentBlob: typeof p.contentBlob === "string" ? p.contentBlob : null,
         ...(topics.length ? { topicId: topics[0].id } : {}),

package/lib/adapters/wechat-pc/v4-sidecar.js

@@ -0,0 +1,112 @@
+"use strict";
+
+/**
+ * WeChat 4.x collection bridge — invokes the forensics-bridge Python sidecar's
+ * `wechat_v4.collect` method (memory key extraction + SQLCipher-4 decryption +
+ * Msg_<md5> parsing) and returns the decrypted messages to the node adapter.
+ *
+ * Why a sidecar: WeChat 4.0 DBs are SQLCipher-4 encrypted with a key cached in
+ * Weixin.exe process memory. Recovering it needs ReadProcessMemory (Windows)
+ * and AES/PBKDF2 — done in Python (`cryptography`), which also sidesteps the
+ * host-node bs3mc ABI problem (the node side never opens the encrypted DB).
+ *
+ * Resolution (all 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
+ *
+ * Returns the sidecar result `{ account, messageCount, dbs, messages }`.
+ * Throws a typed Error (code on .code) the adapter maps to a sync failure.
+ */
+
+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/wechat-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);
+  // Windows commonly ships `python`; *nix `python3`. Try both.
+  list.push(process.platform === "win32" ? "python" : "python3");
+  list.push(process.platform === "win32" ? "python3" : "python");
+  return [...new Set(list)];
+}
+
+/**
+ * @param {object} [opts]
+ * @param {number} [opts.limit]        max messages
+ * @param {string} [opts.key]          pre-extracted 64-hex key (skips memory scan)
+ * @param {string} [opts.pythonExe]
+ * @param {string} [opts.bridgeDir]
+ * @param {number} [opts.timeoutMs]    collect timeout (default 120s)
+ * @param {(msg:object)=>void} [opts.onProgress]
+ * @param {object} [opts._supervisorFactory]  test seam → returns a SidecarSupervisor-like
+ * @returns {Promise<{account:string,messageCount:number,dbs:object[],messages:object[]}>}
+ */
+async function collectWeChatV4(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(
+      `wechat-pc v4: 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.key) params.key = opts.key;
+
+  let lastErr = null;
+  for (const py of pythonCandidates(opts.pythonExe)) {
+    const command = [py, "-m", "forensics_bridge.ipc_server"];
+    const sup = makeSupervisor(command, bridgeDir);
+    try {
+      await sup.start({ readyTimeoutMs: opts.readyTimeoutMs || 15_000 });
+      const result = await sup.invoke("wechat_v4.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 WeChat-side failures (key/app/db) must surface immediately — the
+      // sidecar ran fine, the data just isn't there. Everything else (python
+      // missing, wrong python without `cryptography`, import errors, spawn
+      // death, handshake timeout) → try the next python candidate.
+      const isDataError = /KEY_NOT_FOUND|KEY_VERIFY|APP_NOT|DB_NOT|APP_NOT_RUNNING|EXTRACT_PERMISSION/i.test(msg);
+      if (isDataError) throw err;
+      // otherwise fall through to the next candidate
+    }
+  }
+  const e = new Error(
+    `wechat-pc v4: could not run forensics-bridge sidecar (tried ${pythonCandidates(opts.pythonExe).join(", ")}). ` +
+      `Install Python 3.11+ with the 'cryptography' package, or set CC_PDH_PYTHON. Last error: ${lastErr && lastErr.message}`,
+  );
+  e.code = "SIDECAR_UNAVAILABLE";
+  throw e;
+}
+
+module.exports = { collectWeChatV4, _internals: { resolveBridgeDir, pythonCandidates } };

package/lib/registry.js

@@ -65,6 +65,26 @@ class AdapterRegistry {
     // depend on it).
     this.entityResolver = opts.entityResolver || null;
 
+    // ADB one-click readiness (Phase: social platforms). When supplied by the
+    // wiring, readiness() treats the named adapters as "collectable via a
+    // rooted-phone USB one-click" — flipping their NO_INPUT / DB_NOT_PULLED
+    // status to "ready (device connected)" or "ADB_DEVICE_NEEDED" depending on
+    // whether a device is currently attached. Keeps the registry generic: the
+    // platform list + the actual `adb devices` probe come from the host wiring.
+    //   opts.adbReadiness = {
+    //     probe: async () => ({ deviceConnected: boolean, serial?: string }),
+    //     oneClickNames: Set<string>,  // adapter names with an *AdbSync path
+    //   }
+    this._adbReadiness =
+      opts.adbReadiness && typeof opts.adbReadiness.probe === "function"
+        ? {
+            probe: opts.adbReadiness.probe,
+            oneClickNames: opts.adbReadiness.oneClickNames instanceof Set
+              ? opts.adbReadiness.oneClickNames
+              : new Set(opts.adbReadiness.oneClickNames || []),
+          }
+        : null;
+
     this._adapters = new Map();
     this._activeSync = null; // name of currently-running adapter, or null
   }
@@ -158,9 +178,24 @@ class AdapterRegistry {
       Number.isInteger(opts.timeoutMs) && opts.timeoutMs > 0
         ? opts.timeoutMs
         : DEFAULT_READINESS_TIMEOUT_MS;
+    // Probe the host's ADB device state ONCE (best-effort) so all ADB
+    // one-click adapters share a single `adb devices` call this round.
+    let adbState = null;
+    if (this._adbReadiness) {
+      try {
+        adbState = await this._withTimeout(
+          Promise.resolve().then(() => this._adbReadiness.probe()),
+          timeoutMs,
+          "adb-probe"
+        );
+      } catch (_e) {
+        adbState = { deviceConnected: false };
+      }
+    }
+
     const reports = [];
     for (const adapter of this._adapters.values()) {
-      const report = await this._probeReadiness(adapter, timeoutMs);
+      const report = await this._probeReadiness(adapter, timeoutMs, adbState);
       // Attach the step-by-step import guide (how to get this source's data
       // into the vault) keyed off the resolved category. Single source of
       // truth in adapter-guide.js — reused by every shell.
@@ -170,7 +205,7 @@ class AdapterRegistry {
     return reports;
   }
 
-  async _probeReadiness(adapter, timeoutMs) {
+  async _probeReadiness(adapter, timeoutMs, adbState) {
     const dd = adapter.dataDisclosure || {};
     const extractMode = adapter.extractMode || "web-api";
     const base = {
@@ -240,6 +275,47 @@ class AdapterRegistry {
     }
 
     const reason = (auth && auth.reason) || "UNKNOWN";
+
+    // ADB one-click platforms (social): the adapter itself has no snapshot yet
+    // (NO_INPUT / INPUT_PATH_REQUIRED / DB_NOT_PULLED), but the platform CAN be
+    // collected in one click from a rooted phone over USB. Reflect the real
+    // device state instead of the misleading "采集需先在手机 App 内…".
+    if (
+      this._adbReadiness &&
+      this._adbReadiness.oneClickNames.has(adapter.name) &&
+      (reason === "NO_INPUT" || reason === "INPUT_PATH_REQUIRED" || reason === "DB_NOT_PULLED")
+    ) {
+      if (adbState && adbState.deviceConnected) {
+        return {
+          ...base,
+          ready: true,
+          status: "ready",
+          category: "device",
+          reason: null,
+          message: "已连接 root 手机，点「一键采集」即可拉取",
+          actionHint: null,
+          mode: "adb-oneclick",
+          lastSyncedAt,
+          lastStatus,
+          lastError,
+        };
+      }
+      const adbDesc = describeReadiness("ADB_DEVICE_NEEDED");
+      return {
+        ...base,
+        ready: false,
+        status: adbDesc.status,
+        category: adbDesc.category,
+        reason: "ADB_DEVICE_NEEDED",
+        message: adbDesc.message,
+        actionHint: adbDesc.actionHint,
+        mode: null,
+        lastSyncedAt,
+        lastStatus,
+        lastError,
+      };
+    }
+
     const desc = describeReadiness(reason);
     const detail = auth && (auth.message || auth.error);
     const message =

package/package.json

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