@chainlesschain/personal-data-hub 0.1.0 → 0.2.1

package/lib/adapters/wechat/key-extractor.js

@@ -0,0 +1,158 @@
+/**
+ * Phase 12 v0.5 — WeChat legacy key extractor (frida-INDEPENDENT).
+ *
+ * Ports sjqz/parsers/wechat_decrypt.py legacy path to Node:
+ *
+ *   key = MD5(IMEI + UIN)[:7].lower()
+ *
+ * Works for WeChat versions < 8.0.X where the IMEI-derived key path is
+ * still active. WeChat 8.0+ requires Frida hook on `sqlite3_key` —
+ * that's Phase 12.6 (frida-dependent) and ships when device + Frida are
+ * available.
+ *
+ * Inputs:
+ *   - wechatDataPath: directory mirroring /data/data/com.tencent.mm/
+ *     after `adb pull` (or PC WeChat Files directory)
+ *   - Optional explicit overrides (imei, uin, manualKey) for testing or
+ *     when CompatibleInfo.cfg parsing fails
+ *
+ * Outputs:
+ *   {
+ *     uin: "1234567890",
+ *     imei: "1234567890abcdef",
+ *     key: "5d41402",         // 7-char hex MD5 prefix
+ *     source: "auth-xml+compatible-cfg" | "manual" | "...",
+ *     warnings: [...]
+ *   }
+ */
+
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const crypto = require("node:crypto");
+
+/**
+ * Extract UIN from shared_prefs/auth_info_key_prefs.xml or
+ * system_config_prefs.xml. UIN may be negative; can also be in
+ * `default_uin` or `_auth_uin` keys depending on WeChat version.
+ */
+function extractUinFromPrefs(wechatDataPath) {
+  const candidates = [
+    path.join(wechatDataPath, "shared_prefs", "auth_info_key_prefs.xml"),
+    path.join(wechatDataPath, "shared_prefs", "system_config_prefs.xml"),
+  ];
+  for (const p of candidates) {
+    if (!fs.existsSync(p)) continue;
+    try {
+      const content = fs.readFileSync(p, "utf-8");
+      const patterns = [
+        /<int name="[^"]*_auth_uin[^"]*"\s+value="(-?\d+)"/,
+        /<int name="default_uin"\s+value="(-?\d+)"/,
+        /<int name="[^"]*uin[^"]*"\s+value="(-?\d+)"/,
+      ];
+      for (const re of patterns) {
+        const m = re.exec(content);
+        if (m) return { uin: m[1], from: path.basename(p) };
+      }
+    } catch (_e) {
+      // Try next candidate
+    }
+  }
+  return { uin: null, from: null };
+}
+
+/**
+ * Extract IMEI / device serial from CompatibleInfo.cfg. The file is a
+ * Java HashMap serialization; we use string-search for 15-digit IMEI
+ * patterns + GUIDs as fallback (matches sjqz approach).
+ */
+function extractImeiFromCompatibleInfo(wechatDataPath) {
+  const cfgPath = path.join(wechatDataPath, "MicroMsg", "CompatibleInfo.cfg");
+  if (!fs.existsSync(cfgPath)) return { imei: null, from: null };
+  try {
+    const buf = fs.readFileSync(cfgPath);
+    const text = buf.toString("binary"); // 8-bit safe — we don't care about decoding
+    // 15-digit IMEI
+    const imeiMatch = /\D(\d{15})\D/.exec(text);
+    if (imeiMatch) return { imei: imeiMatch[1], from: "CompatibleInfo.cfg (15-digit)" };
+    // Fallback: 14-digit + check digit pattern
+    const imei14 = /\D(\d{14})\D/.exec(text);
+    if (imei14) return { imei: imei14[1], from: "CompatibleInfo.cfg (14-digit)" };
+    // Fallback: GUID-like
+    const guid = /([0-9a-f]{32})/i.exec(text);
+    if (guid) return { imei: guid[1], from: "CompatibleInfo.cfg (guid)" };
+  } catch (_e) {}
+  return { imei: null, from: null };
+}
+
+/**
+ * Derive the SQLCipher key.
+ *
+ * @param {string} imei
+ * @param {string|number} uin
+ * @returns {string} 7-char hex prefix of MD5(IMEI+UIN), lowercase
+ */
+function deriveLegacyKey(imei, uin) {
+  if (typeof imei !== "string" || imei.length === 0) {
+    throw new Error("deriveLegacyKey: imei required");
+  }
+  if (uin == null) throw new Error("deriveLegacyKey: uin required");
+  const raw = String(imei) + String(uin);
+  return crypto.createHash("md5").update(raw, "utf-8").digest("hex").slice(0, 7).toLowerCase();
+}
+
+/**
+ * Top-level: extract key from a pulled WeChat data directory.
+ *
+ * @param {object} opts
+ * @param {string} opts.wechatDataPath   directory like the pulled
+ *                                       /data/data/com.tencent.mm/ tree
+ * @param {string} [opts.uin]            override (skip auth XML parse)
+ * @param {string} [opts.imei]           override (skip CompatibleInfo)
+ * @returns {object}  { uin, imei, key, source, warnings }
+ */
+function extractWeChatKey(opts = {}) {
+  if (!opts.wechatDataPath || typeof opts.wechatDataPath !== "string") {
+    throw new Error("extractWeChatKey: opts.wechatDataPath required");
+  }
+  const warnings = [];
+
+  let uin = opts.uin || null;
+  let uinSource = "manual";
+  if (!uin) {
+    const r = extractUinFromPrefs(opts.wechatDataPath);
+    uin = r.uin;
+    uinSource = r.from || "missing";
+    if (!uin) warnings.push("UIN not found in shared_prefs — adapter unusable without manual override");
+  }
+
+  let imei = opts.imei || null;
+  let imeiSource = "manual";
+  if (!imei) {
+    const r = extractImeiFromCompatibleInfo(opts.wechatDataPath);
+    imei = r.imei;
+    imeiSource = r.from || "missing";
+    if (!imei) warnings.push("IMEI not found in CompatibleInfo.cfg — adapter unusable without manual override");
+  }
+
+  if (!uin || !imei) {
+    return { uin, imei, key: null, source: `uin:${uinSource} | imei:${imeiSource}`, warnings };
+  }
+
+  const key = deriveLegacyKey(imei, uin);
+  return {
+    uin,
+    imei,
+    key,
+    source: `uin:${uinSource} | imei:${imeiSource}`,
+    warnings,
+  };
+}
+
+module.exports = {
+  extractWeChatKey,
+  deriveLegacyKey,
+  extractUinFromPrefs,
+  extractImeiFromCompatibleInfo,
+};

package/lib/adapters/wechat/key-providers/frida-key-provider.js

@@ -0,0 +1,244 @@
+/**
+ * Phase 12.6.3 — FridaKeyProvider (v1 hot path).
+ *
+ * Attaches frida to a live WeChat process (com.tencent.mm) on a rooted
+ * Android device, injects the wechat-key-hook agent (see
+ * frida-agent/wechat-key-hook.js), waits for the first sqlite3_key
+ * onEnter, captures the 32-byte hex key, then detaches.
+ *
+ * Why detach immediately:
+ *   §18.6 anti-detection — minimize injection window so WeChat's
+ *   ptrace-tracer / mem-scanner doesn't catch frida-gum sitting in
+ *   the process. We hold the script alive only as long as it takes
+ *   the user to touch a chat thread (typically 1-3s).
+ *
+ * Wire to KeyProvider:
+ *   getKey() resolves with lowercase 64-char hex on success, or
+ *   rejects with one of the typed error codes:
+ *     - FRIDA_BINDING_MISSING : opts.frida not provided and require()
+ *                               of "frida" failed (binding not installed)
+ *     - WECHAT_NOT_RUNNING    : device.attach() threw on package name
+ *     - FRIDA_ATTACH_FAILED   : any other attach/createScript error
+ *     - HOOK_FAILED           : agent reported error event before key
+ *     - WCDB_KEY_TIMEOUT      : no key event within timeoutMs
+ *
+ * Test seam: opts.frida overrides the lazy require("frida"), so unit
+ * tests inject a mock device manager without touching the real binding.
+ */
+"use strict";
+
+const { KeyProvider } = require("./key-provider-base");
+const { loadAgentScript } = require("../frida-agent/loader");
+
+class FridaKeyProvider extends KeyProvider {
+  /**
+   * @param {object} opts
+   * @param {object} [opts.frida]       injected nodejs binding (test seam);
+   *                                    if absent, lazy require("frida")
+   * @param {string} [opts.deviceId]    Frida device id (USB device default
+   *                                    if omitted; "local" for Wear/host)
+   * @param {string} [opts.packageName="com.tencent.mm"]
+   * @param {number} [opts.timeoutMs=30000]
+   * @param {Function} [opts.agentLoader]  test seam: returns agent script
+   *                                       text; defaults to loadAgentScript
+   * @param {Function} [opts.logger]    optional log({level, ...evt})
+   */
+  constructor(opts = {}) {
+    super();
+    if (!opts || typeof opts !== "object") {
+      throw new Error("FridaKeyProvider: opts required");
+    }
+    this._fridaInjected = opts.frida || null;
+    this._deviceId = opts.deviceId || null;
+    this._packageName = opts.packageName || "com.tencent.mm";
+    this._timeoutMs = Number.isFinite(opts.timeoutMs) && opts.timeoutMs > 0
+      ? opts.timeoutMs
+      : 30_000;
+    this._agentLoader = typeof opts.agentLoader === "function"
+      ? opts.agentLoader
+      : loadAgentScript;
+    this._logger = typeof opts.logger === "function" ? opts.logger : null;
+    this._lastTelemetry = null;
+  }
+
+  get name() {
+    return "frida";
+  }
+
+  getLastTelemetry() {
+    return this._lastTelemetry;
+  }
+
+  _log(evt) {
+    if (this._logger) {
+      try { this._logger(evt); } catch (_e) { /* swallow logger faults */ }
+    }
+  }
+
+  _loadFrida() {
+    if (this._fridaInjected) return this._fridaInjected;
+    try {
+      // eslint-disable-next-line global-require
+      return require("frida");
+    } catch (err) {
+      const e = new Error(
+        "FridaKeyProvider: frida nodejs binding not installed. " +
+        "Install with `npm install frida` on the host, or pass opts.frida. " +
+        "Underlying error: " + (err && err.message ? err.message : String(err))
+      );
+      e.code = "FRIDA_BINDING_MISSING";
+      throw e;
+    }
+  }
+
+  async _getDevice(frida) {
+    if (this._deviceId) {
+      const dev = await frida.getDevice(this._deviceId);
+      return dev;
+    }
+    // No id → first USB device
+    if (typeof frida.getUsbDevice === "function") {
+      return await frida.getUsbDevice();
+    }
+    return await frida.getDeviceManager().getUsbDevice();
+  }
+
+  /**
+   * @returns {Promise<string>} 64-char lowercase hex SQLCipher key
+   */
+  async getKey(_callOpts) {
+    const telemetry = {
+      startedAt: Date.now(),
+      packageName: this._packageName,
+      deviceId: this._deviceId,
+      hooked: [],
+      errors: [],
+      keySource: null,
+      durationMs: null,
+    };
+
+    const frida = this._loadFrida();
+    let device, session, script;
+
+    try {
+      device = await this._getDevice(frida);
+    } catch (err) {
+      const e = new Error(
+        "FridaKeyProvider: failed to acquire Frida device" +
+        (this._deviceId ? ` (${this._deviceId})` : "") +
+        ": " + (err && err.message ? err.message : String(err))
+      );
+      e.code = "FRIDA_ATTACH_FAILED";
+      this._lastTelemetry = telemetry;
+      throw e;
+    }
+
+    try {
+      session = await device.attach(this._packageName);
+    } catch (err) {
+      const errMsg = err && err.message ? err.message : String(err);
+      const e = new Error(
+        `FridaKeyProvider: device.attach(${this._packageName}) failed: ${errMsg}`
+      );
+      // Distinguish "process not found" vs other attach errors
+      e.code = /unable to find process|process not found/i.test(errMsg)
+        ? "WECHAT_NOT_RUNNING"
+        : "FRIDA_ATTACH_FAILED";
+      this._lastTelemetry = telemetry;
+      throw e;
+    }
+
+    try {
+      const agentSrc = this._agentLoader();
+      script = await session.createScript(agentSrc);
+    } catch (err) {
+      const e = new Error(
+        "FridaKeyProvider: createScript failed: " +
+        (err && err.message ? err.message : String(err))
+      );
+      e.code = "FRIDA_ATTACH_FAILED";
+      this._lastTelemetry = telemetry;
+      // Clean up the session before throwing
+      try { await session.detach(); } catch (_e) {}
+      throw e;
+    }
+
+    // Promise resolves on the first 'key' message; rejects on the first
+    // 'error' (after script load) or after timeoutMs without key.
+    const keyHex = await new Promise((resolve, reject) => {
+      let settled = false;
+      let timer = null;
+
+      const cleanup = async () => {
+        if (timer) { clearTimeout(timer); timer = null; }
+        try { await script.unload(); } catch (_e) {}
+        try { await session.detach(); } catch (_e) {}
+      };
+
+      const onMessage = (message, _data) => {
+        if (settled) return;
+        if (!message || message.type !== "send" || !message.payload) return;
+        const evt = message.payload;
+        this._log({ level: "info", kind: "frida-message", evt });
+
+        if (evt.kind === "hooked") {
+          telemetry.hooked.push({ symbol: evt.symbol, module: evt.module });
+          return;
+        }
+        if (evt.kind === "module-waiting") {
+          return; // informational
+        }
+        if (evt.kind === "key") {
+          settled = true;
+          telemetry.keySource = evt.source;
+          telemetry.durationMs = Date.now() - telemetry.startedAt;
+          cleanup().then(() => resolve(String(evt.hex || "").toLowerCase()));
+          return;
+        }
+        if (evt.kind === "error") {
+          telemetry.errors.push(evt.message);
+          // Don't reject on individual hook errors; we may still get a
+          // key from a fallback symbol. Only reject on timeout.
+          return;
+        }
+      };
+
+      script.message.connect(onMessage);
+
+      script.load().catch((err) => {
+        if (settled) return;
+        settled = true;
+        cleanup().then(() => {
+          const e = new Error(
+            "FridaKeyProvider: script.load failed: " +
+            (err && err.message ? err.message : String(err))
+          );
+          e.code = "FRIDA_ATTACH_FAILED";
+          reject(e);
+        });
+      });
+
+      timer = setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        cleanup().then(() => {
+          const last = telemetry.errors.length > 0
+            ? ` (last hook error: ${telemetry.errors[telemetry.errors.length - 1]})`
+            : "";
+          const e = new Error(
+            `FridaKeyProvider: no sqlite3_key call within ${this._timeoutMs}ms` +
+            (telemetry.hooked.length === 0 ? " — libwcdb.so never loaded; " +
+              "did the user touch a chat thread?" : "") + last
+          );
+          e.code = "WCDB_KEY_TIMEOUT";
+          reject(e);
+        });
+      }, this._timeoutMs);
+    });
+
+    this._lastTelemetry = telemetry;
+    return keyHex;
+  }
+}
+
+module.exports = { FridaKeyProvider };

package/lib/adapters/wechat/key-providers/index.js

@@ -0,0 +1,22 @@
+"use strict";
+
+const { KeyProvider } = require("./key-provider-base");
+const { MD5KeyProvider } = require("./md5-key-provider");
+
+// FridaKeyProvider depends on the optional `frida` nodejs binding. Load
+// lazily so users on devices without the binding can still use the v0.5
+// MD5 path. Phase 12.6.3 ships the implementation.
+let FridaKeyProvider = null;
+try {
+  // eslint-disable-next-line global-require
+  ({ FridaKeyProvider } = require("./frida-key-provider"));
+} catch (_e) {
+  // Module not yet built / frida binding missing — leave null. Callers
+  // that need it should require it directly so they see the real error.
+}
+
+module.exports = {
+  KeyProvider,
+  MD5KeyProvider,
+  FridaKeyProvider,
+};

package/lib/adapters/wechat/key-providers/key-provider-base.js

@@ -0,0 +1,44 @@
+/**
+ * Phase 12.6 — KeyProvider interface contract.
+ *
+ * The wechat-adapter is key-source agnostic: it only knows about an
+ * object with `getKey()` returning a Promise<string> (32-hex SQLCipher
+ * key for v0.5 7-char prefix, or full 64-hex for Frida hot path).
+ *
+ * Two implementations:
+ *   - MD5KeyProvider (v0.5, frida-INDEPENDENT) — derives MD5(IMEI+UIN)[:7]
+ *     from on-disk WeChat data dir. Works for WeChat < 8.0.x.
+ *   - FridaKeyProvider (v1, frida-DEPENDENT)  — attaches frida to live
+ *     WeChat process and hooks sqlite3_key. Works for WeChat 8.0+.
+ *
+ * Both expose the same getKey() shape so wechat-adapter.js does not
+ * branch on version.
+ */
+"use strict";
+
+class KeyProvider {
+  /**
+   * Return the SQLCipher key (lowercase hex). Throw on failure.
+   *
+   * Optional opts (per design §18.2):
+   *   - wxid : string  WeChat user identifier (some providers need this)
+   *   - dbPath : string path to the SQLCipher DB being opened
+   *
+   * @param {{wxid?: string, dbPath?: string}} [_opts]
+   * @returns {Promise<string>}
+   */
+  // eslint-disable-next-line no-unused-vars
+  async getKey(_opts) {
+    throw new Error("KeyProvider.getKey: must be overridden by subclass");
+  }
+
+  /**
+   * Provider name for telemetry / error attribution. Subclasses
+   * override.
+   */
+  get name() {
+    return "key-provider-base";
+  }
+}
+
+module.exports = { KeyProvider };

package/lib/adapters/wechat/key-providers/md5-key-provider.js

@@ -0,0 +1,81 @@
+/**
+ * Phase 12.6.1 — MD5KeyProvider (v0.5 legacy WeChat < 8.0 path).
+ *
+ * Wraps the existing key-extractor.js (MD5(IMEI+UIN)[:7] lowercase)
+ * behind the KeyProvider interface. Pure frida-independent: works from
+ * a pulled WeChat data directory (`adb pull /data/data/com.tencent.mm/`).
+ *
+ * Usage:
+ *   const provider = new MD5KeyProvider({
+ *     wechatDataPath: "/tmp/com.tencent.mm",
+ *     // optional manual overrides for testing or when CompatibleInfo.cfg
+ *     // parsing fails
+ *     uin: "1234567890",
+ *     imei: "1234567890abcdef",
+ *   });
+ *   const key = await provider.getKey();
+ */
+"use strict";
+
+const { KeyProvider } = require("./key-provider-base");
+const { extractWeChatKey } = require("../key-extractor");
+
+class MD5KeyProvider extends KeyProvider {
+  /**
+   * @param {object} opts
+   * @param {string} opts.wechatDataPath  directory mirroring the pulled
+   *                                       /data/data/com.tencent.mm/ tree
+   * @param {string} [opts.uin]            override (skip auth XML parse)
+   * @param {string} [opts.imei]           override (skip CompatibleInfo)
+   * @param {Function} [opts.extractor]    DI seam — defaults to
+   *                                       extractWeChatKey
+   */
+  constructor(opts = {}) {
+    super();
+    if (!opts || typeof opts !== "object") {
+      throw new Error("MD5KeyProvider: opts required");
+    }
+    if (!opts.wechatDataPath || typeof opts.wechatDataPath !== "string") {
+      throw new Error("MD5KeyProvider: opts.wechatDataPath required");
+    }
+    this._wechatDataPath = opts.wechatDataPath;
+    this._uinOverride = opts.uin || null;
+    this._imeiOverride = opts.imei || null;
+    this._extractor = typeof opts.extractor === "function"
+      ? opts.extractor
+      : extractWeChatKey;
+    this._lastResult = null;
+  }
+
+  get name() {
+    return "md5";
+  }
+
+  /**
+   * @returns {Promise<string>}  7-char lowercase hex MD5 prefix
+   */
+  async getKey() {
+    const result = this._extractor({
+      wechatDataPath: this._wechatDataPath,
+      uin: this._uinOverride,
+      imei: this._imeiOverride,
+    });
+    this._lastResult = result;
+    if (!result || !result.key) {
+      const warnings = (result && result.warnings) || [];
+      const reason = warnings.length > 0 ? warnings.join("; ") : "key extraction returned empty";
+      throw new Error(`MD5KeyProvider.getKey: ${reason}`);
+    }
+    return result.key;
+  }
+
+  /**
+   * Last extraction result for telemetry / debugging — exposes uin /
+   * imei sources and warnings. Returns null until getKey() called.
+   */
+  getLastResult() {
+    return this._lastResult;
+  }
+}
+
+module.exports = { MD5KeyProvider };