@chainlesschain/personal-data-hub 0.2.0 → 0.2.2

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

@@ -129,27 +129,88 @@ class WeChatDBReader {
       .map((r) => r.name);
   }
 
+  /**
+   * Discover actual column names via `PRAGMA table_info(<table>)` so
+   * uppercase/lowercase divergence across WeChat builds doesn't blow up
+   * the SELECT. Returns a Map<lowercased_name, actual_name>.
+   *
+   * Post-sjqz audit defence — sjqz schema docs show some column-case
+   * variation across versions; failing late at SELECT yields a confusing
+   * "no such column" error rather than a clean fallback path.
+   */
+  _columnMap(table) {
+    if (!this._db) return new Map();
+    try {
+      const rows = this._db.prepare(`PRAGMA table_info(${table})`).all();
+      return new Map(rows.map((r) => [String(r.name).toLowerCase(), r.name]));
+    } catch (_e) {
+      return new Map();
+    }
+  }
+
+  /**
+   * Resolve a list of desired column names against the actual table
+   * schema. Returns the actual column names quoted for SQL use; throws
+   * if any required column is missing (caller catches and surfaces a
+   * "schema-mismatch" error to the host).
+   */
+  _resolveColumns(table, desiredNames, { required = true } = {}) {
+    const map = this._columnMap(table);
+    const resolved = [];
+    const missing = [];
+    for (const name of desiredNames) {
+      const actual = map.get(name.toLowerCase());
+      if (actual) resolved.push(actual);
+      else if (required) missing.push(name);
+    }
+    if (missing.length > 0 && required) {
+      const err = new Error(
+        `WeChatDBReader: table '${table}' missing required columns: ${missing.join(", ")} ` +
+          `(available: ${Array.from(map.values()).join(", ")})`,
+      );
+      err.code = "WECHAT_SCHEMA_MISMATCH";
+      throw err;
+    }
+    return resolved;
+  }
+
   /**
    * Fetch up to `limit` messages since `sinceMsgSvrId` (per design doc
    * §6 OQ-6 watermark = per-talker last msgSvrId). For initial v0 we
    * accept a global watermark and let the adapter post-filter per
    * talker.
+   *
+   * Column names resolved via PRAGMA table_info to survive case-drift
+   * across WeChat versions (sjqz audit defence).
    */
   fetchMessages({ sinceMsgSvrId = 0, limit = 1000, talker = null } = {}) {
     if (!this._db) throw new Error("WeChatDBReader: call open() first");
-    let sql = "SELECT msgId, msgSvrId, talker, content, type, createTime, isSend, status FROM message";
+    const cols = this._resolveColumns("message", [
+      "msgId",
+      "msgSvrId",
+      "talker",
+      "content",
+      "type",
+      "createTime",
+      "isSend",
+      "status",
+    ]);
+    let sql = `SELECT ${cols.join(", ")} FROM message`;
     const params = [];
     const where = [];
     if (sinceMsgSvrId) {
-      where.push("msgSvrId > ?");
+      // Use the resolved column name in WHERE / ORDER BY to match case.
+      const msgSvrIdCol = cols[1];
+      where.push(`${msgSvrIdCol} > ?`);
       params.push(sinceMsgSvrId);
     }
     if (talker) {
-      where.push("talker = ?");
+      const talkerCol = cols[2];
+      where.push(`${talkerCol} = ?`);
       params.push(talker);
     }
     if (where.length > 0) sql += " WHERE " + where.join(" AND ");
-    sql += " ORDER BY msgSvrId ASC LIMIT ?";
+    sql += ` ORDER BY ${cols[1]} ASC LIMIT ?`;
     params.push(limit);
     return this._db.prepare(sql).all(...params);
   }
@@ -157,14 +218,31 @@ class WeChatDBReader {
   /**
    * Fetch contacts. WeChat rcontact has many columns; we pull the ones
    * relevant for normalization.
+   *
+   * sjqz parity (wechat.py:262-263): excludes `@stranger` (unconfirmed
+   * friend requests) and `fake_*` (WeChat internal placeholder accounts).
+   * Without this filter the vault gets polluted with junk Person entities
+   * that never represent real contacts.
+   *
+   * @param {object} [opts]
+   * @param {number} [opts.limit=5000]
+   * @param {boolean} [opts.includeJunk=false]  true to skip the
+   *   stranger/fake filter (debug / forensic use only)
    */
-  fetchContacts({ limit = 5000 } = {}) {
+  fetchContacts({ limit = 5000, includeJunk = false } = {}) {
     if (!this._db) throw new Error("WeChatDBReader: call open() first");
-    return this._db
-      .prepare(
-        "SELECT username, alias, nickname, conRemark, type FROM rcontact LIMIT ?",
-      )
-      .all(limit);
+    const cols = this._resolveColumns("rcontact", [
+      "username",
+      "alias",
+      "nickname",
+      "conRemark",
+      "type",
+    ]);
+    const usernameCol = cols[0];
+    const sql = includeJunk
+      ? `SELECT ${cols.join(", ")} FROM rcontact LIMIT ?`
+      : `SELECT ${cols.join(", ")} FROM rcontact WHERE ${usernameCol} NOT LIKE '%@stranger' AND ${usernameCol} NOT LIKE 'fake_%' LIMIT ?`;
+    return this._db.prepare(sql).all(limit);
   }
 
   /**

package/lib/adapters/wechat/env-probe.js

@@ -0,0 +1,218 @@
+/**
+ * Phase 12.6.4 — WeChat env-probe.
+ *
+ * Inspects the connected Android device (via `adb`) and decides which
+ * KeyProvider strategy is viable:
+ *
+ *   - suggestedKeyProvider: "md5" | "frida" | "unsupported"
+ *
+ * Decision tree:
+ *   - WeChat < 8.0  → "md5"   (legacy MD5(IMEI+UIN)[:7] path works)
+ *   - WeChat 8.0+   → "frida" (need live hook; requires root + frida-server)
+ *   - WeChat absent / device unreachable → "unsupported"
+ *
+ * Each capability is probed independently so UI can show a checklist.
+ * All shell commands are routed through an injected `exec()` so unit
+ * tests don't spawn real processes.
+ *
+ * Wire shape:
+ *   {
+ *     ok: boolean,                  // overall — true iff suggestedKeyProvider !== "unsupported"
+ *     suggestedKeyProvider: "md5" | "frida" | "unsupported",
+ *     reasons: string[],            // human strings for why suggestion chosen
+ *     device: {
+ *       reachable: boolean,
+ *       serial: string | null,
+ *       abi: string | null,         // arm64-v8a / armeabi-v7a / x86_64
+ *     },
+ *     root: {
+ *       detected: boolean,
+ *       magiskInstalled: boolean,
+ *     },
+ *     frida: {
+ *       serverRunning: boolean,
+ *       port: number | null,
+ *     },
+ *     wechat: {
+ *       installed: boolean,
+ *       versionName: string | null,
+ *       majorVersion: number | null,
+ *     },
+ *     warnings: string[],
+ *   }
+ */
+"use strict";
+
+// Lazy require of child_process so test injection beats the import
+function defaultExec() {
+  // eslint-disable-next-line global-require
+  const cp = require("node:child_process");
+  return (cmd, opts = {}) => new Promise((resolve) => {
+    cp.exec(cmd, { encoding: "utf-8", timeout: 5000, ...opts }, (err, stdout, stderr) => {
+      resolve({
+        code: err ? (err.code || 1) : 0,
+        stdout: String(stdout || ""),
+        stderr: String(stderr || ""),
+      });
+    });
+  });
+}
+
+async function probeDevice(exec) {
+  const out = { reachable: false, serial: null, abi: null };
+  const r = await exec("adb devices");
+  if (r.code !== 0) return out;
+  const lines = r.stdout.split(/\r?\n/);
+  // Header: "List of devices attached" then "<serial>\tdevice"
+  for (const line of lines) {
+    const m = /^(\S+)\s+device\s*$/.exec(line);
+    if (m) {
+      out.reachable = true;
+      out.serial = m[1];
+      break;
+    }
+  }
+  if (!out.reachable) return out;
+  const abiR = await exec("adb shell getprop ro.product.cpu.abi");
+  out.abi = abiR.code === 0 ? abiR.stdout.trim() || null : null;
+  return out;
+}
+
+async function probeRoot(exec) {
+  const out = { detected: false, magiskInstalled: false };
+  // `su -c id` succeeds (uid=0) only on rooted devices
+  const su = await exec('adb shell "su -c id" 2>&1');
+  if (su.code === 0 && /uid=0/.test(su.stdout)) out.detected = true;
+  // which magisk (Magisk command-line)
+  const ma = await exec('adb shell "command -v magisk"');
+  if (ma.code === 0 && ma.stdout.trim()) out.magiskInstalled = true;
+  return out;
+}
+
+async function probeFridaServer(exec) {
+  const out = { serverRunning: false, port: null };
+  // Look for frida-server in process list (matches frida-server-* prebuilds)
+  const ps = await exec('adb shell "pgrep -f frida-server" 2>&1');
+  if (ps.code === 0 && /^\d+/m.test(ps.stdout.trim())) out.serverRunning = true;
+  // Default port 27042; check if it's listening
+  const ns = await exec('adb shell "netstat -tln 2>/dev/null | grep -E \':27042\\b\'"');
+  if (ns.code === 0 && ns.stdout.includes("27042")) {
+    out.serverRunning = true;
+    out.port = 27042;
+  } else if (out.serverRunning) {
+    out.port = 27042;
+  }
+  return out;
+}
+
+async function probeWeChat(exec) {
+  const out = { installed: false, versionName: null, majorVersion: null };
+  const r = await exec('adb shell "dumpsys package com.tencent.mm | grep versionName"');
+  if (r.code !== 0) return out;
+  const m = /versionName=([\d.]+)/i.exec(r.stdout);
+  if (!m) return out;
+  out.installed = true;
+  out.versionName = m[1];
+  const major = parseInt(m[1].split(".")[0], 10);
+  out.majorVersion = Number.isFinite(major) ? major : null;
+  return out;
+}
+
+/**
+ * Decide suggested KeyProvider given probed capabilities.
+ * Exported separately so callers can also pass synthetic facts.
+ */
+function decide({ device, root, frida, wechat }) {
+  const reasons = [];
+  if (!device.reachable) {
+    return { suggestedKeyProvider: "unsupported", reasons: ["No adb device reachable"] };
+  }
+  if (!wechat.installed) {
+    return { suggestedKeyProvider: "unsupported", reasons: ["WeChat (com.tencent.mm) not installed"] };
+  }
+  const major = wechat.majorVersion;
+  if (major != null && major < 8) {
+    reasons.push(`WeChat ${wechat.versionName} (< 8.0) — legacy MD5(IMEI+UIN) path supported`);
+    return { suggestedKeyProvider: "md5", reasons };
+  }
+  // 8.0+ requires frida
+  if (!root.detected) {
+    return {
+      suggestedKeyProvider: "unsupported",
+      reasons: [`WeChat ${wechat.versionName || "8.x"} requires root for SQLCipher key extraction, root not detected`],
+    };
+  }
+  if (!frida.serverRunning) {
+    return {
+      suggestedKeyProvider: "unsupported",
+      reasons: [
+        `WeChat ${wechat.versionName || "8.x"} requires Frida hook`,
+        "frida-server not running on device — see Frida Setup runbook",
+      ],
+    };
+  }
+  reasons.push(`WeChat ${wechat.versionName} (≥ 8.0) — Frida hook on libwcdb.so sqlite3_key`);
+  if (!root.magiskInstalled) {
+    reasons.push("Magisk not detected — DenyList configuration unavailable; reverse-detection may be weaker");
+  }
+  return { suggestedKeyProvider: "frida", reasons };
+}
+
+/**
+ * Top-level probe.
+ *
+ * @param {object} [opts]
+ * @param {Function} [opts.exec]  injected exec(cmd, opts) → {code, stdout, stderr}
+ * @returns {Promise<object>}     full probe shape (see file header)
+ */
+async function probe(opts = {}) {
+  const exec = typeof opts.exec === "function" ? opts.exec : defaultExec();
+  const warnings = [];
+
+  const device = await probeDevice(exec);
+  if (!device.reachable) {
+    return {
+      ok: false,
+      suggestedKeyProvider: "unsupported",
+      reasons: ["No adb device reachable — enable USB debugging and reconnect"],
+      device,
+      root: { detected: false, magiskInstalled: false },
+      frida: { serverRunning: false, port: null },
+      wechat: { installed: false, versionName: null, majorVersion: null },
+      warnings,
+    };
+  }
+
+  const [root, frida, wechat] = await Promise.all([
+    probeRoot(exec),
+    probeFridaServer(exec),
+    probeWeChat(exec),
+  ]);
+
+  if (device.abi && !/^arm/.test(device.abi)) {
+    warnings.push(`ABI ${device.abi} — Frida prebuilt may need manual build for non-ARM target`);
+  }
+
+  const { suggestedKeyProvider, reasons } = decide({ device, root, frida, wechat });
+
+  return {
+    ok: suggestedKeyProvider !== "unsupported",
+    suggestedKeyProvider,
+    reasons,
+    device,
+    root,
+    frida,
+    wechat,
+    warnings,
+  };
+}
+
+module.exports = {
+  probe,
+  decide,
+  // exposed for fine-grained testing
+  probeDevice,
+  probeRoot,
+  probeFridaServer,
+  probeWeChat,
+};

package/lib/adapters/wechat/frida-agent/loader.js

@@ -0,0 +1,74 @@
+/**
+ * Phase 12.6.2 — Frida agent loader (host side).
+ *
+ * Reads the raw agent JS so FridaKeyProvider can pass it to
+ * `session.createScript(text)`. Also exposes `runUnderMock()` so the
+ * host can unit-test the agent's behavior by injecting fake Frida
+ * globals (Module / Interceptor / Process / send / setTimeout).
+ *
+ * The agent itself (wechat-key-hook.js) is plain JS — no `require` or
+ * `module.exports` — because Frida loads it as a text blob inside the
+ * target process. The loader hides that detail from callers.
+ */
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const vm = require("node:vm");
+
+const AGENT_PATH = path.join(__dirname, "wechat-key-hook.js");
+
+function loadAgentScript() {
+  return fs.readFileSync(AGENT_PATH, "utf-8");
+}
+
+/**
+ * Execute the agent script in a sandboxed context where the caller
+ * supplies the Frida globals. Used for unit tests.
+ *
+ * @param {object} mocks
+ * @param {object} mocks.Module     mock with findExportByName(modName, sym)
+ * @param {object} mocks.Process    mock with findModuleByName(modName)
+ * @param {object} mocks.Interceptor mock with attach(addr, handlers)
+ * @param {Function} mocks.send     captures send() calls
+ * @param {Function} [mocks.setTimeout]  defaults to global setTimeout
+ * @returns {object}  the sandbox context after execution
+ */
+function runAgentUnderMock(mocks = {}) {
+  if (!mocks.Module || typeof mocks.Module.findExportByName !== "function") {
+    throw new Error("runAgentUnderMock: mocks.Module.findExportByName required");
+  }
+  if (!mocks.Process || typeof mocks.Process.findModuleByName !== "function") {
+    throw new Error("runAgentUnderMock: mocks.Process.findModuleByName required");
+  }
+  if (!mocks.Interceptor || typeof mocks.Interceptor.attach !== "function") {
+    throw new Error("runAgentUnderMock: mocks.Interceptor.attach required");
+  }
+  if (typeof mocks.send !== "function") {
+    throw new Error("runAgentUnderMock: mocks.send required");
+  }
+  const sandbox = {
+    Module: mocks.Module,
+    Process: mocks.Process,
+    Interceptor: mocks.Interceptor,
+    send: mocks.send,
+    setTimeout: mocks.setTimeout || setTimeout,
+    // Frida injects Memory at runtime; tests that exercise the ascii-hex
+    // key-read path inject a mock with readCString(ptr, maxLen). Tests
+    // that don't touch it get a no-op stub so the agent module loads
+    // cleanly even when the hook itself never calls readCString.
+    Memory: mocks.Memory || {
+      readCString: () => null,
+    },
+  };
+  const ctx = vm.createContext(sandbox);
+  const src = loadAgentScript();
+  vm.runInContext(src, ctx, { filename: "wechat-key-hook.js" });
+  return sandbox;
+}
+
+module.exports = {
+  AGENT_PATH,
+  loadAgentScript,
+  runAgentUnderMock,
+};

package/lib/adapters/wechat/frida-agent/wechat-key-hook.js

@@ -0,0 +1,248 @@
+/**
+ * Phase 12.6.2 — Frida agent: WeChat SQLCipher key hook.
+ *
+ * This script runs INSIDE the WeChat process (com.tencent.mm) after
+ * being injected by the FridaKeyProvider on the host. It hooks the
+ * sqlite3_key family of symbols in libwcdb.so (WeChat's SQLCipher fork)
+ * and sends the captured 32-byte key hex back to the host via Frida's
+ * `send()` channel.
+ *
+ * Wire contract (host expects):
+ *   { kind: "key", hex: "<lowercase hex>", source: "<symbol-name>" }
+ *   { kind: "hooked", symbol: "<symbol>", module: "libwcdb.so" }
+ *   { kind: "error", message: "<reason>" }
+ *   { kind: "module-waiting", module: "libwcdb.so" }
+ *
+ * Design references:
+ *   - Adapter_WeChat_SQLCipher.md §18.3 (agent script structure)
+ *   - §18.6 (anti-detection — hook at module-load time)
+ *
+ * Notes on portability:
+ *   - This file is loaded by the host as raw text and passed verbatim
+ *     to `session.createScript(...)`. It MUST NOT use any node `require()`
+ *     or host-only APIs. Frida injects its own runtime (Module,
+ *     Interceptor, Process, send, etc.) at runtime.
+ *   - Keep dependencies on host helpers (e.g. esbuild) zero. The whole
+ *     agent is ≤ 120 LOC of plain JS — no compilation step needed.
+ */
+
+/* eslint-disable */
+/* global Module, Interceptor, Process, send, setTimeout */
+
+"use strict";
+
+(function () {
+  // sjqz-verified module name is `libWCDB.so` (uppercase); some WeChat
+  // builds ship lowercase. Try both — first match wins, no extra cost
+  // because Process.findModuleByName is a cheap lookup.
+  var TARGET_MODULES = ["libWCDB.so", "libwcdb.so"];
+  // Primary symbol per §18.3. Add fallbacks below — version drift will
+  // shift the export name; host treats first hit as authoritative.
+  var SYMBOLS = [
+    "sqlite3_key",
+    "sqlite3_key_v2",
+    "wcdb_setkey",
+    "WCDBKeyDerive",
+    // C++-mangled symbols (Itanium ABI) — rare but seen in WCDB 1.x
+    "_ZN4WCDB8Database13setCipherKeyERKNSt6__ndk112basic_stringIcNS1_11char_traitsIcEENS1_9allocatorIcEEEE",
+  ];
+
+  function bytesToHex(buf) {
+    if (!buf || buf.byteLength === 0) return "";
+    var bytes = new Uint8Array(buf);
+    var out = "";
+    for (var i = 0; i < bytes.length; i++) {
+      var b = bytes[i].toString(16);
+      if (b.length < 2) b = "0" + b;
+      out += b;
+    }
+    return out;
+  }
+
+  // Track which symbol fired first; only emit the first key event so
+  // the host detaches quickly (anti-detection §18.6 #4).
+  var fired = false;
+
+  // Sig-aware arg index map. The host treats the first 'key' event as
+  // authoritative, so picking the wrong index for v2 = host gets the
+  // database NAME pointer (e.g. "main") and DB opens fail silently.
+  //   sqlite3_key(sqlite3 *db, const void *pKey, int nKey)
+  //     args[0]=db,            args[1]=key, args[2]=len
+  //   sqlite3_key_v2(sqlite3 *db, const char *zDbName, const void *pKey, int nKey)
+  //     args[0]=db, args[1]=name, args[2]=key, args[3]=len
+  //   wcdb_setkey / WCDBKeyDerive: unknown sig — assume sqlite3_key shape
+  //   Mangled C++: WCDB::Database::setCipherKey(*this, const std::string&)
+  //     args[0]=this, args[1]=&string (length needs .size()) — not handled
+  //     here; emit error so the host falls back to MD5 path.
+  function argIndicesFor(symbolName) {
+    if (symbolName === "sqlite3_key_v2") {
+      return { key: 2, len: 3, sig: "v2" };
+    }
+    if (symbolName.indexOf("_ZN4WCDB") === 0) {
+      return { key: -1, len: -1, sig: "mangled-cpp" };
+    }
+    return { key: 1, len: 2, sig: "v1" };
+  }
+
+  // sjqz extract_wechat_key.py uses Memory.readCString(args[1]) for the
+  // key — meaning some WeChat builds pass the key as a NUL-terminated
+  // 64-char ASCII hex string. Other builds (and the original SQLCipher
+  // contract) pass 32 raw bytes. We can disambiguate by `len`:
+  //   - len === 32 → raw 32-byte key → readByteArray + bytesToHex
+  //   - len === 64 → ASCII hex string → readCString
+  //   - anything else → emit error, host falls back to MD5 path
+  function makeHook(symbolName) {
+    var idx = argIndicesFor(symbolName);
+    return {
+      onEnter: function (args) {
+        if (fired) return;
+        if (idx.key < 0) {
+          send({
+            kind: "error",
+            message:
+              "unsupported symbol signature: " +
+              symbolName +
+              " — host should fall back to MD5(IMEI+UIN) key path",
+          });
+          return;
+        }
+        try {
+          var len = args[idx.len].toInt32();
+          if (len <= 0 || len > 256) {
+            send({
+              kind: "error",
+              message:
+                "implausible key length " + len + " at " + symbolName,
+            });
+            return;
+          }
+          var hex;
+          var format;
+          if (len === 64) {
+            // ASCII hex string (sjqz-verified path on WeChat 7.x/8.0 libWCDB)
+            var s = Memory.readCString(args[idx.key], len);
+            if (!s || s.length === 0) {
+              send({
+                kind: "error",
+                message: "readCString returned empty at " + symbolName,
+              });
+              return;
+            }
+            hex = s.toLowerCase();
+            format = "ascii-hex";
+          } else if (len === 32) {
+            // Raw 32-byte key — convert to 64-char hex
+            var buf = args[idx.key].readByteArray(len);
+            hex = bytesToHex(buf);
+            format = "raw-bytes";
+          } else {
+            // Ambiguous length — could be either. Emit both interpretations
+            // and let the host try each against the DB until one succeeds.
+            var bufAmb = args[idx.key].readByteArray(len);
+            var hexFromBytes = bytesToHex(bufAmb);
+            var hexFromString = null;
+            try {
+              var sAmb = Memory.readCString(args[idx.key], len);
+              if (sAmb) hexFromString = sAmb.toLowerCase();
+            } catch (_e) {
+              // readCString may fault on non-NUL-terminated bytes; ignore.
+            }
+            fired = true;
+            send({
+              kind: "key",
+              hex: hexFromBytes,
+              alt: hexFromString,
+              source: symbolName,
+              sig: idx.sig,
+              format: "ambiguous",
+              length: len,
+            });
+            return;
+          }
+          if (!hex) {
+            send({
+              kind: "error",
+              message: "empty key buffer at " + symbolName,
+            });
+            return;
+          }
+          fired = true;
+          send({
+            kind: "key",
+            hex: hex,
+            source: symbolName,
+            sig: idx.sig,
+            format: format,
+            length: len,
+          });
+        } catch (e) {
+          send({
+            kind: "error",
+            message:
+              "hook exception at " +
+              symbolName +
+              ": " +
+              (e && e.message ? e.message : String(e)),
+          });
+        }
+      },
+    };
+  }
+
+  function tryAttachOnModule(moduleName) {
+    var mod = Process.findModuleByName(moduleName);
+    if (!mod) return false;
+    var attached = 0;
+    for (var i = 0; i < SYMBOLS.length; i++) {
+      var addr = Module.findExportByName(moduleName, SYMBOLS[i]);
+      if (!addr) continue;
+      try {
+        Interceptor.attach(addr, makeHook(SYMBOLS[i]));
+        send({ kind: "hooked", symbol: SYMBOLS[i], module: moduleName });
+        attached++;
+      } catch (e) {
+        send({
+          kind: "error",
+          message:
+            "Interceptor.attach failed for " +
+            SYMBOLS[i] +
+            ": " +
+            (e && e.message ? e.message : String(e)),
+        });
+      }
+    }
+    return attached > 0;
+  }
+
+  function tryAttach() {
+    for (var i = 0; i < TARGET_MODULES.length; i++) {
+      if (tryAttachOnModule(TARGET_MODULES[i])) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  // Module-load polling — §18.6 #1 "hook at module-load time before
+  // anti-detection thread runs". WeChat lazy-loads libWCDB when the
+  // first DB opens, so we can't always find it at script start.
+  if (!tryAttach()) {
+    send({ kind: "module-waiting", module: TARGET_MODULES.join("|") });
+    var attempts = 0;
+    var poll = function () {
+      attempts++;
+      if (tryAttach()) return;
+      if (attempts >= 60) {
+        // 60 attempts × 500ms = 30s ceiling, matches host timeoutMs
+        send({
+          kind: "error",
+          message:
+            TARGET_MODULES.join("|") + " did not load within 30s",
+        });
+        return;
+      }
+      setTimeout(poll, 500);
+    };
+    setTimeout(poll, 500);
+  }
+})();

package/lib/adapters/wechat/index.js

@@ -5,6 +5,9 @@ const { parseContent, parseXmlAttrs, extractTag, isGroupTalker, TYPE_NAMES, APPM
 const { extractWeChatKey, deriveLegacyKey, extractUinFromPrefs, extractImeiFromCompatibleInfo } = require("./key-extractor");
 const { WeChatDBReader, KNOWN_PRAGMA_PROFILES } = require("./db-reader");
 const { normalizeMessage, normalizeContact, wxidToPersonId } = require("./normalize");
+const { KeyProvider, MD5KeyProvider, FridaKeyProvider } = require("./key-providers");
+const envProbe = require("./env-probe");
+const { bootstrapWechatAdapter } = require("./bootstrap");
 
 module.exports = {
   WechatAdapter,
@@ -25,4 +28,10 @@ module.exports = {
   normalizeWeChatMessage: normalizeMessage,
   normalizeWeChatContact: normalizeContact,
   wxidToWeChatPersonId: wxidToPersonId,
+  WeChatKeyProvider: KeyProvider,
+  WeChatMD5KeyProvider: MD5KeyProvider,
+  WeChatFridaKeyProvider: FridaKeyProvider,
+  probeWeChatEnv: envProbe.probe,
+  decideWeChatKeyProvider: envProbe.decide,
+  bootstrapWechatAdapter,
 };