@chainlesschain/personal-data-hub 0.1.0 → 0.2.1

package/__tests__/adapters/wechat-frida-integration.test.js

@@ -0,0 +1,149 @@
+"use strict";
+
+import { describe, it, expect, vi } from "vitest";
+
+const {
+  WechatAdapter,
+  WeChatFridaKeyProvider,
+} = require("../../lib/adapters/wechat");
+
+/**
+ * Phase 12.6.5 — integration: WechatAdapter.authenticate flow against
+ * a mock FridaKeyProvider. We don't open a real SQLCipher DB here —
+ * that requires a fixture + better-sqlite3-multiple-ciphers compiled
+ * against the host's Node ABI, and is covered separately in the v0.5
+ * suite. Goal of this slice: prove the adapter's KeyProvider DI seam
+ * works identically for the Frida path.
+ */
+
+function mockFrida({ keyHex, throwOnAttach, delayMs = 0 } = {}) {
+  const script = {
+    message: { connect: (h) => { script._handler = h; } },
+    load: async () => {
+      setTimeout(() => {
+        if (!script._handler) return;
+        script._handler({ type: "send", payload: {
+          kind: "hooked", symbol: "sqlite3_key", module: "libwcdb.so",
+        } });
+        script._handler({ type: "send", payload: {
+          kind: "key", hex: keyHex, source: "sqlite3_key",
+        } });
+      }, delayMs);
+    },
+    unload: async () => {},
+  };
+  const session = {
+    createScript: async () => script,
+    detach: async () => {},
+  };
+  const device = {
+    attach: async () => {
+      if (throwOnAttach) throw new Error(throwOnAttach);
+      return session;
+    },
+  };
+  return {
+    getDevice: async () => device,
+    getUsbDevice: async () => device,
+  };
+}
+
+describe("WechatAdapter + FridaKeyProvider — DI integration", () => {
+  it("authenticate succeeds when frida provides a key", async () => {
+    // dbPath needs to point to a real file for the existsSync gate
+    const fs = require("node:fs");
+    const path = require("node:path");
+    const os = require("node:os");
+    const tmpDb = path.join(os.tmpdir(), `wechat-mock-${Date.now()}.db`);
+    fs.writeFileSync(tmpDb, "fake sqlite header");
+
+    const frida = mockFrida({ keyHex: "ab".repeat(32) /* 64 hex */ });
+    const keyProvider = new WeChatFridaKeyProvider({
+      frida,
+      deviceId: "TEST",
+      agentLoader: () => "/* test agent */",
+    });
+
+    const adapter = new WechatAdapter({
+      account: { uin: "1234567890" },
+      dbPath: tmpDb,
+      keyProvider,
+    });
+
+    const r = await adapter.authenticate();
+    expect(r.ok).toBe(true);
+    expect(r.account).toBe("1234567890");
+
+    try { fs.unlinkSync(tmpDb); } catch (_e) { /* test cleanup */ }
+  });
+
+  it("authenticate reports NO_KEY_PROVIDER when keyProvider absent", async () => {
+    const fs = require("node:fs");
+    const path = require("node:path");
+    const os = require("node:os");
+    const tmpDb = path.join(os.tmpdir(), `wechat-mock-${Date.now()}.db`);
+    fs.writeFileSync(tmpDb, "fake");
+
+    const adapter = new WechatAdapter({
+      account: { uin: "1234567890" },
+      dbPath: tmpDb,
+      // keyProvider omitted on purpose
+    });
+    const r = await adapter.authenticate();
+    expect(r.ok).toBe(false);
+    expect(r.reason).toBe("NO_KEY_PROVIDER");
+
+    try { fs.unlinkSync(tmpDb); } catch (_e) { /* test cleanup */ }
+  });
+
+  it("authenticate reports KEY_PROVIDER_THREW when Frida times out", async () => {
+    const fs = require("node:fs");
+    const path = require("node:path");
+    const os = require("node:os");
+    const tmpDb = path.join(os.tmpdir(), `wechat-mock-${Date.now()}.db`);
+    fs.writeFileSync(tmpDb, "fake");
+
+    // Mock with no messages → will timeout
+    const session = {
+      createScript: async () => ({
+        message: { connect: () => {} },
+        load: async () => {},
+        unload: async () => {},
+      }),
+      detach: async () => {},
+    };
+    const frida = {
+      getDevice: async () => ({ attach: async () => session }),
+      getUsbDevice: async () => ({ attach: async () => session }),
+    };
+    const keyProvider = new WeChatFridaKeyProvider({
+      frida,
+      deviceId: "TEST",
+      agentLoader: () => "",
+      timeoutMs: 30,
+    });
+
+    const adapter = new WechatAdapter({
+      account: { uin: "1234567890" },
+      dbPath: tmpDb,
+      keyProvider,
+    });
+
+    const r = await adapter.authenticate();
+    expect(r.ok).toBe(false);
+    expect(r.reason).toBe("KEY_PROVIDER_THREW");
+    expect(r.error).toMatch(/30ms/);
+
+    try { fs.unlinkSync(tmpDb); } catch (_e) { /* test cleanup */ }
+  });
+
+  it("DB_NOT_PULLED takes precedence over keyProvider absence", async () => {
+    const adapter = new WechatAdapter({
+      account: { uin: "1234567890" },
+      dbPath: "/definitely/not/a/real/path/wechat.db",
+    });
+    const r = await adapter.authenticate();
+    expect(r.ok).toBe(false);
+    expect(r.reason).toBe("DB_NOT_PULLED");
+  });
+});

package/__tests__/adapters/wechat-frida-key-provider.test.js

@@ -0,0 +1,188 @@
+"use strict";
+
+import { describe, it, expect, vi } from "vitest";
+
+const { FridaKeyProvider } = require("../../lib/adapters/wechat/key-providers/frida-key-provider");
+
+/** Helper that builds a mock frida binding with a scripted message timeline. */
+function makeMockFrida({ onAttachThrow, onCreateScriptThrow, onLoadThrow, messages = [], deviceId = "device" }) {
+  const ops = {
+    unloadCalled: 0,
+    detachCalled: 0,
+    loadCalled: 0,
+    messageHandler: null,
+  };
+  const script = {
+    message: {
+      connect: (handler) => { ops.messageHandler = handler; },
+    },
+    load: vi.fn(async () => {
+      ops.loadCalled++;
+      if (onLoadThrow) throw onLoadThrow;
+      // Replay the scripted messages on next tick so .connect handler is
+      // wired before the first send fires.
+      setTimeout(() => {
+        for (const m of messages) {
+          if (ops.messageHandler) ops.messageHandler({ type: "send", payload: m });
+        }
+      }, 0);
+    }),
+    unload: vi.fn(async () => { ops.unloadCalled++; }),
+  };
+  const session = {
+    createScript: vi.fn(async () => {
+      if (onCreateScriptThrow) throw onCreateScriptThrow;
+      return script;
+    }),
+    detach: vi.fn(async () => { ops.detachCalled++; }),
+  };
+  const device = {
+    attach: vi.fn(async (pkg) => {
+      if (onAttachThrow) throw onAttachThrow;
+      device._attachedTo = pkg;
+      return session;
+    }),
+  };
+  const frida = {
+    getDevice: vi.fn(async (id) => {
+      device._id = id;
+      return device;
+    }),
+    getUsbDevice: vi.fn(async () => device),
+  };
+  return { frida, device, session, script, ops };
+}
+
+describe("FridaKeyProvider — construction", () => {
+  it("defaults packageName to com.tencent.mm", () => {
+    const p = new FridaKeyProvider({});
+    expect(p._packageName).toBe("com.tencent.mm");
+  });
+
+  it("name is frida", () => {
+    const p = new FridaKeyProvider({});
+    expect(p.name).toBe("frida");
+  });
+
+  it("getKey throws FRIDA_BINDING_MISSING when frida not available", async () => {
+    const p = new FridaKeyProvider({});
+    try {
+      await p.getKey();
+      throw new Error("should have thrown");
+    } catch (err) {
+      expect(err.code).toBe("FRIDA_BINDING_MISSING");
+    }
+  });
+});
+
+describe("FridaKeyProvider — happy path", () => {
+  it("captures key hex and detaches", async () => {
+    const keyHex = "00112233445566778899aabbccddeeff" +
+                   "ffeeddccbbaa99887766554433221100";
+    const { frida, ops } = makeMockFrida({
+      messages: [
+        { kind: "hooked", symbol: "sqlite3_key", module: "libwcdb.so" },
+        { kind: "key", hex: keyHex.toUpperCase(), source: "sqlite3_key" },
+      ],
+    });
+    const p = new FridaKeyProvider({ frida, deviceId: "Z1", agentLoader: () => "/* mock agent */" });
+    const k = await p.getKey();
+    expect(k).toBe(keyHex); // lowercased
+    expect(ops.unloadCalled).toBe(1);
+    expect(ops.detachCalled).toBe(1);
+    const tel = p.getLastTelemetry();
+    expect(tel.keySource).toBe("sqlite3_key");
+    expect(tel.hooked).toHaveLength(1);
+    expect(tel.durationMs).toBeGreaterThanOrEqual(0);
+  });
+
+  it("uses USB device when no deviceId provided", async () => {
+    const { frida } = makeMockFrida({
+      messages: [{ kind: "key", hex: "aa" + "00".repeat(31), source: "sqlite3_key" }],
+    });
+    const p = new FridaKeyProvider({ frida, agentLoader: () => "/* mock */" });
+    await p.getKey();
+    expect(frida.getUsbDevice).toHaveBeenCalled();
+    expect(frida.getDevice).not.toHaveBeenCalled();
+  });
+});
+
+describe("FridaKeyProvider — error paths", () => {
+  it("WECHAT_NOT_RUNNING when attach reports process not found", async () => {
+    const { frida } = makeMockFrida({
+      onAttachThrow: new Error("unable to find process with name 'com.tencent.mm'"),
+    });
+    const p = new FridaKeyProvider({ frida, deviceId: "Z1", agentLoader: () => "" });
+    await expect(p.getKey()).rejects.toMatchObject({ code: "WECHAT_NOT_RUNNING" });
+  });
+
+  it("FRIDA_ATTACH_FAILED on generic attach error", async () => {
+    const { frida } = makeMockFrida({
+      onAttachThrow: new Error("permission denied"),
+    });
+    const p = new FridaKeyProvider({ frida, deviceId: "Z1", agentLoader: () => "" });
+    await expect(p.getKey()).rejects.toMatchObject({ code: "FRIDA_ATTACH_FAILED" });
+  });
+
+  it("FRIDA_ATTACH_FAILED + session cleanup when createScript throws", async () => {
+    const { frida, ops } = makeMockFrida({
+      onCreateScriptThrow: new Error("syntax error in agent"),
+    });
+    const p = new FridaKeyProvider({ frida, deviceId: "Z1", agentLoader: () => "BAD" });
+    await expect(p.getKey()).rejects.toMatchObject({ code: "FRIDA_ATTACH_FAILED" });
+    // Even though createScript threw, the session was already attached;
+    // implementation cleans it up in the catch path.
+    expect(ops.detachCalled).toBe(1);
+  });
+
+  it("WCDB_KEY_TIMEOUT when no key event in time", async () => {
+    const { frida, ops } = makeMockFrida({
+      messages: [{ kind: "hooked", symbol: "sqlite3_key", module: "libwcdb.so" }],
+    });
+    const p = new FridaKeyProvider({
+      frida,
+      deviceId: "Z1",
+      timeoutMs: 50,
+      agentLoader: () => "",
+    });
+    await expect(p.getKey()).rejects.toMatchObject({ code: "WCDB_KEY_TIMEOUT" });
+    expect(ops.unloadCalled).toBe(1);
+    expect(ops.detachCalled).toBe(1);
+  });
+
+  it("non-fatal hook errors are recorded but don't reject", async () => {
+    const keyHex = "ee" + "00".repeat(31);
+    const { frida } = makeMockFrida({
+      messages: [
+        { kind: "error", message: "Interceptor.attach failed for WCDBKeyDerive: not found" },
+        { kind: "hooked", symbol: "sqlite3_key", module: "libwcdb.so" },
+        { kind: "key", hex: keyHex, source: "sqlite3_key" },
+      ],
+    });
+    const p = new FridaKeyProvider({ frida, deviceId: "Z1", agentLoader: () => "" });
+    const k = await p.getKey();
+    expect(k).toBe(keyHex);
+    expect(p.getLastTelemetry().errors).toContain("Interceptor.attach failed for WCDBKeyDerive: not found");
+  });
+});
+
+describe("FridaKeyProvider — logger DI", () => {
+  it("logger receives frida-message events", async () => {
+    const events = [];
+    const { frida } = makeMockFrida({
+      messages: [
+        { kind: "hooked", symbol: "sqlite3_key", module: "libwcdb.so" },
+        { kind: "key", hex: "ff" + "00".repeat(31), source: "sqlite3_key" },
+      ],
+    });
+    const p = new FridaKeyProvider({
+      frida,
+      deviceId: "Z1",
+      agentLoader: () => "",
+      logger: (e) => events.push(e),
+    });
+    await p.getKey();
+    expect(events.some((e) => e.kind === "frida-message" && e.evt.kind === "hooked")).toBe(true);
+    expect(events.some((e) => e.kind === "frida-message" && e.evt.kind === "key")).toBe(true);
+  });
+});

package/__tests__/adapters/wechat-md5-key-provider.test.js

@@ -0,0 +1,101 @@
+"use strict";
+
+import { describe, it, expect } from "vitest";
+
+const {
+  WeChatKeyProvider,
+  WeChatMD5KeyProvider,
+} = require("../../lib/adapters/wechat");
+
+describe("WeChatKeyProvider — base contract", () => {
+  it("getKey throws on bare base instance (subclass must override)", async () => {
+    const base = new WeChatKeyProvider();
+    await expect(base.getKey()).rejects.toThrow(/must be overridden/);
+  });
+
+  it("name defaults to key-provider-base", () => {
+    const base = new WeChatKeyProvider();
+    expect(base.name).toBe("key-provider-base");
+  });
+});
+
+describe("WeChatMD5KeyProvider — construction validation", () => {
+  it("throws if opts missing", () => {
+    expect(() => new WeChatMD5KeyProvider()).toThrow(/wechatDataPath/);
+  });
+
+  it("throws if wechatDataPath missing", () => {
+    expect(() => new WeChatMD5KeyProvider({ uin: "1" })).toThrow(/wechatDataPath/);
+  });
+
+  it("name returns md5", () => {
+    const p = new WeChatMD5KeyProvider({ wechatDataPath: "/tmp/wx" });
+    expect(p.name).toBe("md5");
+  });
+});
+
+describe("WeChatMD5KeyProvider — extractor DI happy path", () => {
+  it("getKey returns hex when extractor yields key", async () => {
+    const extractor = (opts) => {
+      expect(opts.wechatDataPath).toBe("/tmp/wx");
+      return {
+        uin: "100200300",
+        imei: "350123456789012",
+        key: "abcdef1",
+        source: "test",
+        warnings: [],
+      };
+    };
+    const p = new WeChatMD5KeyProvider({
+      wechatDataPath: "/tmp/wx",
+      extractor,
+    });
+    const key = await p.getKey();
+    expect(key).toBe("abcdef1");
+    expect(p.getLastResult().uin).toBe("100200300");
+    expect(p.getLastResult().imei).toBe("350123456789012");
+  });
+
+  it("getKey passes uin/imei overrides through to extractor", async () => {
+    let passedOpts = null;
+    const extractor = (opts) => {
+      passedOpts = opts;
+      return { key: "0000000", uin: opts.uin, imei: opts.imei, warnings: [] };
+    };
+    const p = new WeChatMD5KeyProvider({
+      wechatDataPath: "/tmp/wx",
+      uin: "999",
+      imei: "deadbeef",
+      extractor,
+    });
+    await p.getKey();
+    expect(passedOpts.uin).toBe("999");
+    expect(passedOpts.imei).toBe("deadbeef");
+  });
+});
+
+describe("WeChatMD5KeyProvider — extractor failure surfaces as throw", () => {
+  it("throws with warnings when extractor returns no key", async () => {
+    const extractor = () => ({
+      uin: null,
+      imei: null,
+      key: null,
+      source: "missing",
+      warnings: ["UIN not found in shared_prefs", "IMEI not found in CompatibleInfo.cfg"],
+    });
+    const p = new WeChatMD5KeyProvider({
+      wechatDataPath: "/tmp/empty",
+      extractor,
+    });
+    await expect(p.getKey()).rejects.toThrow(/UIN not found/);
+  });
+
+  it("throws with generic reason when warnings empty", async () => {
+    const extractor = () => ({ key: null, warnings: [] });
+    const p = new WeChatMD5KeyProvider({
+      wechatDataPath: "/tmp/empty",
+      extractor,
+    });
+    await expect(p.getKey()).rejects.toThrow(/extraction returned empty/);
+  });
+});