@chainlesschain/personal-data-hub 0.2.0 → 0.2.1

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,67 @@
+/**
+ * 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,
+  };
+  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,126 @@
+/**
+ * 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 () {
+  var TARGET_MODULE = "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;
+
+  function makeHook(symbolName) {
+    return {
+      onEnter: function (args) {
+        if (fired) return;
+        try {
+          // sqlite3_key signature: int sqlite3_key(sqlite3 *db, const void *pKey, int nKey)
+          // args[1] = key bytes, args[2] = key length
+          var len = args[2].toInt32();
+          if (len <= 0 || len > 256) {
+            send({ kind: "error", message: "implausible key length " + len + " at " + symbolName });
+            return;
+          }
+          var buf = args[1].readByteArray(len);
+          var hex = bytesToHex(buf);
+          if (!hex) {
+            send({ kind: "error", message: "empty key buffer at " + symbolName });
+            return;
+          }
+          fired = true;
+          send({ kind: "key", hex: hex, source: symbolName });
+        } catch (e) {
+          send({ kind: "error", message: "hook exception at " + symbolName + ": " + (e && e.message ? e.message : String(e)) });
+        }
+      },
+    };
+  }
+
+  function tryAttach() {
+    var mod = Process.findModuleByName(TARGET_MODULE);
+    if (!mod) return false;
+    var attached = 0;
+    for (var i = 0; i < SYMBOLS.length; i++) {
+      var addr = Module.findExportByName(TARGET_MODULE, SYMBOLS[i]);
+      if (!addr) continue;
+      try {
+        Interceptor.attach(addr, makeHook(SYMBOLS[i]));
+        send({ kind: "hooked", symbol: SYMBOLS[i], module: TARGET_MODULE });
+        attached++;
+      } catch (e) {
+        send({ kind: "error", message: "Interceptor.attach failed for " + SYMBOLS[i] + ": " + (e && e.message ? e.message : String(e)) });
+      }
+    }
+    return attached > 0;
+  }
+
+  // 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_MODULE });
+    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_MODULE + " 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,
 };

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,
+};