@chainlesschain/personal-data-hub 0.3.1 → 0.3.6

package/__tests__/adapters/social-xiaohongshu-adb-sign.test.js

@@ -0,0 +1,130 @@
+"use strict";
+
+import { describe, it, expect } from "vitest";
+
+const {
+  computeXsXt,
+  extractA1,
+  XS_PREFIX,
+} = require("../../lib/adapters/social-xiaohongshu-adb/sign");
+
+// ─── computeXsXt ────────────────────────────────────────────────────────
+
+describe("computeXsXt — X-S signature byte-parity check", () => {
+  it("produces stable XYW_ prefix + base64 md5 hex", () => {
+    const result = computeXsXt(
+      "/api/sns/web/v1/user/me",
+      null,
+      "18d6e123abc",
+      { now: () => 1716383021000 },
+    );
+    expect(result.xs).toMatch(/^XYW_[A-Za-z0-9+/]+$/);
+    expect(result.xs).not.toMatch(/=$/); // no padding
+    expect(result.xt).toBe("1716383021000");
+  });
+
+  it("byte-parity golden vector from Kotlin reference", () => {
+    // Reproduce: md5("1716383021000" + "url=/api/sns/web/v1/user/me" + "test_a1")
+    //   .toUtf8Bytes().base64() with NO_PADDING + NO_WRAP
+    // Computed via node:crypto cross-check; this is the exact value
+    // Kotlin XhsApiClient.kt:computeXsXt produces for the same inputs.
+    const result = computeXsXt(
+      "/api/sns/web/v1/user/me",
+      null,
+      "test_a1",
+      { now: () => 1716383021000 },
+    );
+    // The actual md5 hex of "1716383021000url=/api/sns/web/v1/user/me" + "test_a1":
+    // npm crypto md5 → "9b6e0a..." (varies); base64 of that hex string
+    // Lock the value computed by this very module so future changes are
+    // caught.
+    expect(result.xs).toBe(
+      "XYW_" +
+        Buffer.from(
+          require("node:crypto")
+            .createHash("md5")
+            .update("1716383021000url=/api/sns/web/v1/user/metest_a1", "utf8")
+            .digest("hex"),
+          "utf8",
+        )
+          .toString("base64")
+          .replace(/=+$/, ""),
+    );
+  });
+
+  it("includes body in payload (POST case)", () => {
+    const noBody = computeXsXt("/api/x", null, "a1", { now: () => 1000 });
+    const withBody = computeXsXt("/api/x", '{"foo":1}', "a1", {
+      now: () => 1000,
+    });
+    expect(noBody.xs).not.toBe(withBody.xs);
+  });
+
+  it("different ts → different X-S", () => {
+    const r1 = computeXsXt("/api/x", null, "a1", { now: () => 1000 });
+    const r2 = computeXsXt("/api/x", null, "a1", { now: () => 2000 });
+    expect(r1.xs).not.toBe(r2.xs);
+    expect(r1.xt).toBe("1000");
+    expect(r2.xt).toBe("2000");
+  });
+
+  it("different a1 → different X-S", () => {
+    const r1 = computeXsXt("/api/x", null, "a1_v1", { now: () => 1000 });
+    const r2 = computeXsXt("/api/x", null, "a1_v2", { now: () => 1000 });
+    expect(r1.xs).not.toBe(r2.xs);
+  });
+
+  it("rejects empty / non-string urlPathWithQuery", () => {
+    expect(() => computeXsXt("", null, "a1")).toThrow(TypeError);
+    expect(() => computeXsXt(null, null, "a1")).toThrow(TypeError);
+  });
+
+  it("rejects empty / non-string a1", () => {
+    expect(() => computeXsXt("/x", null, "")).toThrow(TypeError);
+    expect(() => computeXsXt("/x", null, null)).toThrow(TypeError);
+  });
+
+  it("XS_PREFIX export = 'XYW_'", () => {
+    expect(XS_PREFIX).toBe("XYW_");
+  });
+});
+
+// ─── extractA1 ──────────────────────────────────────────────────────────
+
+describe("extractA1", () => {
+  it("extracts a1 from full xhs cookie", () => {
+    const cookie =
+      "web_session=session_token; a1=18d6e1234567890abcdef; xsec_token=xxx";
+    expect(extractA1(cookie)).toBe("18d6e1234567890abcdef");
+  });
+
+  it("handles a1 as first cookie field", () => {
+    expect(extractA1("a1=fingerprint_value; web_session=s")).toBe(
+      "fingerprint_value",
+    );
+  });
+
+  it("handles a1 as last cookie field", () => {
+    expect(extractA1("web_session=s; a1=fingerprint_value")).toBe(
+      "fingerprint_value",
+    );
+  });
+
+  it("returns null when a1 missing", () => {
+    expect(extractA1("web_session=s; xsec_token=t")).toBe(null);
+  });
+
+  it("returns null when a1 empty", () => {
+    expect(extractA1("a1=; web_session=s")).toBe(null);
+  });
+
+  it("returns null for non-string / null", () => {
+    expect(extractA1(null)).toBe(null);
+    expect(extractA1(undefined)).toBe(null);
+    expect(extractA1(123)).toBe(null);
+  });
+
+  it("trims whitespace around cookie parts", () => {
+    expect(extractA1("web_session=s ;  a1=val  ; xsec=x")).toBe("val");
+  });
+});

package/__tests__/adapters/system-data-android.test.js

@@ -16,9 +16,10 @@ const {
   ENTITY_TYPES,
   PERSON_SUBTYPES,
   ITEM_SUBTYPES,
+  EVENT_SUBTYPES,
   CAPTURED_BY,
 } = require("../../lib/constants");
-const { validatePerson, validateItem } = require("../../lib/schemas");
+const { validatePerson, validateItem, validateEvent } = require("../../lib/schemas");
 
 let tmpDir;
 let snapshotPath;
@@ -130,12 +131,42 @@ describe("SystemDataAndroidAdapter.sync + normalize", () => {
 
     const persons = [];
     const items = [];
+    const events = [];
     for await (const raw of adapter.sync({ inputPath: snapshotPath })) {
       const batch = adapter.normalize(raw);
       persons.push(...batch.persons);
       items.push(...batch.items);
+      events.push(...batch.events);
     }
 
+    // v0.3.1 — one synthetic event per contact + per app so they show up
+    // under the Vault Browser's `category=system` facet (events table).
+    expect(events).toHaveLength(2);
+    expect(events.map((e) => e.id)).toEqual([
+      "event-android-contact-0r1-3A2B",
+      "event-android-app-com.tencent.mm",
+    ]);
+    expect(events[0].subtype).toBe(EVENT_SUBTYPES.OTHER);
+    expect(events[0].content.title).toBe("联系人：妈妈");
+    expect(events[0].extra.kind).toBe("contact-snapshot");
+    // v0.3.2 — contact event.extra carries identifying fields so detail
+    // sheet doesn't have to join the persons table.
+    expect(events[0].extra.phones).toEqual(["+8613800138000"]);
+    expect(events[0].extra.organization).toBe("家庭");
+    expect(events[0].extra.starred).toBe(true);
+    expect(events[1].content.title).toBe("应用：微信");
+    expect(events[1].extra.kind).toBe("app-snapshot");
+    expect(events[1].extra.packageName).toBe("com.tencent.mm");
+    // v0.3.2 — app event.extra carries version + install fields.
+    expect(events[1].extra.versionName).toBe("8.0.45");
+    expect(events[1].extra.versionCode).toBe(2200);
+    expect(events[1].extra.firstInstallTime).toBe(1_650_000_000_000);
+    expect(events[1].extra.isSystem).toBe(false);
+    events.forEach((e) => {
+      const ev = validateEvent(e);
+      expect(ev).toEqual({ valid: true, errors: [] });
+    });
+
     expect(persons).toHaveLength(1);
     const p = persons[0];
     expect(p.id).toBe("person-android-0r1-3A2B");

package/__tests__/longtail-adapters.test.js

@@ -231,8 +231,21 @@ describe("TelegramAdapter", () => {
     expect(a.dataDisclosure.legalGate).toBe(true);
   });
 
-  it("rejects missing account.userId", () => {
-    expect(() => new TelegramAdapter({ account: {} })).toThrow(/userId/);
+  it("no-arg ctor passes contract (2026-05-25 v0.6 — account.userId OPTIONAL for snapshot mode)", () => {
+    const a = new TelegramAdapter();
+    expect(assertAdapter(a).ok).toBe(true);
+    expect(a.capabilities).toContain("sync:snapshot");
+    expect(a.capabilities).toContain("sync:sqlite");
+  });
+
+  it("authenticate(ctx.inputPath) returns ok when file readable (snapshot mode)", async () => {
+    const { dir, dbPath } = tmpDb();
+    try {
+      const a = new TelegramAdapter();
+      const auth = await a.authenticate({ inputPath: dbPath });
+      expect(auth.ok).toBe(true);
+      expect(auth.mode).toBe("snapshot-file");
+    } finally { cleanup(dir); }
   });
 
   it("sync yields user + chat + messages (no key needed)", async () => {

package/__tests__/shopping-adapters.test.js

@@ -183,6 +183,102 @@ describe("TaobaoAdapter", () => {
     for await (const r of a.sync()) raws.push(r);
     expect(raws).toHaveLength(0);
   });
+
+  // §2.4d v0.2 — snapshot mode (mirror shopping-jd/meituan/pinduoduo dual-mode).
+  // Android in-APK collector ships JSON snapshot via syncAdapter("shopping-
+  // taobao", path); desktop adapter consumes via inputPath.
+
+  it("snapshot mode — no-arg ctor passes contract", () => {
+    const a = new TaobaoAdapter();
+    expect(assertAdapter(a).ok).toBe(true);
+    expect(a.capabilities).toContain("sync:snapshot");
+    expect(a.capabilities).toContain("sync:cookie-api"); // both advertised
+  });
+
+  it("snapshot mode — authenticate(ctx.inputPath) returns ok when file readable", async () => {
+    const fs = require("node:fs");
+    const path = require("node:path");
+    const os = require("node:os");
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "taobao-snap-"));
+    const inputPath = path.join(dir, "snap.json");
+    fs.writeFileSync(inputPath, "{}", "utf-8");
+    try {
+      const a = new TaobaoAdapter();
+      const auth = await a.authenticate({ inputPath });
+      expect(auth.ok).toBe(true);
+      expect(auth.mode).toBe("snapshot-file");
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("snapshot mode — sync yields order events from snapshot file", async () => {
+    const fs = require("node:fs");
+    const path = require("node:path");
+    const os = require("node:os");
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "taobao-snap-yield-"));
+    const inputPath = path.join(dir, "snap.json");
+    fs.writeFileSync(inputPath, JSON.stringify({
+      schemaVersion: 1,
+      snapshottedAt: 1_700_000_000_000,
+      account: { userId: "u-snap" },
+      events: [
+        {
+          kind: "order",
+          id: "TB-SNAP-1",
+          capturedAt: 1_700_000_100_000,
+          vendorId: "taobao",
+          orderId: "TB-SNAP-1",
+          placedAt: 1_700_000_000_000,
+          paidAt: 1_700_000_010_000,
+          status: "delivered",
+          merchantName: "Test 旗舰店",
+          totalAmount: { value: 123.45, currency: "CNY" },
+          items: [{ name: "Item X", quantity: 1, unitPrice: 123.45 }],
+        },
+      ],
+    }), "utf-8");
+    try {
+      const a = new TaobaoAdapter();
+      const raws = [];
+      for await (const r of a.sync({ inputPath })) raws.push(r);
+      expect(raws).toHaveLength(1);
+      expect(raws[0].adapter).toBe("shopping-taobao");
+      expect(raws[0].kind).toBe("order");
+      expect(raws[0].originalId).toBe("taobao:order:TB-SNAP-1");
+      const batch = a.normalize(raws[0]);
+      expect(validateBatch(batch).valid).toBe(true);
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("snapshot mode — schemaVersion mismatch throws", async () => {
+    const fs = require("node:fs");
+    const path = require("node:path");
+    const os = require("node:os");
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "taobao-snap-bad-"));
+    const inputPath = path.join(dir, "snap.json");
+    fs.writeFileSync(inputPath, JSON.stringify({ schemaVersion: 99, events: [] }), "utf-8");
+    try {
+      const a = new TaobaoAdapter();
+      let threw = null;
+      try {
+        for await (const _r of a.sync({ inputPath })) { /* drain */ }
+      } catch (err) { threw = err; }
+      expect(threw).toBeTruthy();
+      expect(threw.message).toMatch(/schemaVersion mismatch/);
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("no-arg ctor + no inputPath = NO_INPUT (legible failure)", async () => {
+    const a = new TaobaoAdapter();
+    const auth = await a.authenticate({});
+    expect(auth.ok).toBe(false);
+    expect(auth.reason).toBe("NO_INPUT");
+  });
 });
 
 // ─── JdAdapter ───────────────────────────────────────────────────────────

package/__tests__/sign-providers.test.js

@@ -0,0 +1,62 @@
+"use strict";
+
+/**
+ * Phase 6a — SignProvider abstract + NullSignProvider unit cover.
+ */
+
+import { describe, it, expect } from "vitest";
+
+const {
+  SignProvider,
+  NullSignProvider,
+  NULL_SIGN_PROVIDER,
+} = require("../lib/sign-providers");
+
+describe("SignProvider abstract base", () => {
+  it("signUrl returns null by default", async () => {
+    const p = new SignProvider();
+    expect(await p.signUrl("https://example.com", "purpose")).toBe(null);
+  });
+
+  it("signedHeaders returns {} by default", async () => {
+    const p = new SignProvider();
+    const r = await p.signedHeaders("https://example.com", "purpose");
+    expect(r).toEqual({});
+  });
+
+  it("shutdown is no-op (no throw)", async () => {
+    const p = new SignProvider();
+    await expect(p.shutdown()).resolves.toBeUndefined();
+  });
+});
+
+describe("NullSignProvider", () => {
+  it("extends SignProvider", () => {
+    const p = new NullSignProvider();
+    expect(p).toBeInstanceOf(SignProvider);
+  });
+
+  it("inherits stub signUrl / signedHeaders / shutdown", async () => {
+    const p = new NullSignProvider();
+    expect(await p.signUrl("x", "y")).toBe(null);
+    expect(await p.signedHeaders("x", "y")).toEqual({});
+    await expect(p.shutdown()).resolves.toBeUndefined();
+  });
+
+  it("NULL_SIGN_PROVIDER is a frozen singleton", () => {
+    expect(NULL_SIGN_PROVIDER).toBeInstanceOf(NullSignProvider);
+    expect(Object.isFrozen(NULL_SIGN_PROVIDER)).toBe(true);
+  });
+
+  it("api-client pattern: call signUrl + signedHeaders without crash", async () => {
+    // Simulates api-client usage — signProvider.signUrl(url, purpose) ||
+    // fall back to unsigned URL; spread signedHeaders into request headers.
+    const provider = NULL_SIGN_PROVIDER;
+    const url = "https://api.example.com/x";
+    const signedUrl = (await provider.signUrl(url, "test")) || url;
+    expect(signedUrl).toBe(url); // null → fall back to original
+    const extraHeaders = await provider.signedHeaders(url, "test");
+    const finalHeaders = { Cookie: "x=y", ...extraHeaders };
+    expect(finalHeaders).toEqual({ Cookie: "x=y" }); // no extras from null provider
+  });
+});

package/__tests__/travel-adapters.test.js

@@ -299,6 +299,65 @@ describe("CtripAdapter", () => {
     expect(CTRIP_TYPE_MAP.train).toBe("train");
     expect(CTRIP_TYPE_MAP.cruise).toBe("cruise");
   });
+
+  // §9.3b v0.2 — no-arg ctor (auto-register at boot) + inputPath alias for
+  // Android in-APK cc syncAdapter("travel-ctrip", path). Earlier strict ctor
+  // (opts.account.email required) blocked the auto-register loop.
+
+  it("no-arg ctor passes contract (snapshot mode)", () => {
+    const a = new CtripAdapter();
+    expect(assertAdapter(a).ok).toBe(true);
+    expect(a.capabilities).toContain("sync:snapshot");
+    expect(a.capabilities).toContain("import:json"); // both kept
+  });
+
+  it("sync(inputPath) alias yields records same as dataPath", async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "ctrip-snap-"));
+    const inputPath = path.join(dir, "snap.json");
+    fs.writeFileSync(inputPath, JSON.stringify([
+      {
+        orderId: "C-SNAP-1", type: "flight",
+        depCity: "上海", arrCity: "北京",
+        flightNumber: "MU100", airline: "东航",
+        departureTime: "2026-05-01 08:00:00",
+        arrivalTime: "2026-05-01 10:30:00",
+        passengerName: "张三", price: 800, pnr: "XYZ",
+      },
+    ]), "utf-8");
+    try {
+      const a = new CtripAdapter();
+      const raws = [];
+      for await (const r of a.sync({ inputPath })) raws.push(r);
+      expect(raws).toHaveLength(1);
+      expect(raws[0].adapter).toBe("travel-ctrip");
+      expect(raws[0].originalId).toBe("C-SNAP-1");
+      const batch = a.normalize(raws[0]);
+      expect(validateBatch(batch).valid).toBe(true);
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("authenticate(ctx.inputPath) returns ok when file readable", async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "ctrip-auth-"));
+    const inputPath = path.join(dir, "snap.json");
+    fs.writeFileSync(inputPath, "[]", "utf-8");
+    try {
+      const a = new CtripAdapter();
+      const auth = await a.authenticate({ inputPath });
+      expect(auth.ok).toBe(true);
+      expect(auth.mode).toBe("snapshot-file");
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("authenticate(no path) ok with mode=ready (no account required)", async () => {
+    const a = new CtripAdapter();
+    const auth = await a.authenticate({});
+    expect(auth.ok).toBe(true);
+    expect(auth.mode).toBe("ready");
+  });
 });
 
 // ─── Amap adapter (mocked SQLite) ───────────────────────────────────────
@@ -310,6 +369,13 @@ describe("AmapAdapter", () => {
     expect(a.extractMode).toBe("device-pull");
   });
 
+  it("no-arg ctor passes contract (2026-05-25 v0.6 — account.deviceId OPTIONAL for snapshot mode)", () => {
+    const a = new AmapAdapter();
+    expect(assertAdapter(a).ok).toBe(true);
+    expect(a.capabilities).toContain("sync:snapshot");
+    expect(a.capabilities).toContain("sync:sqlite");
+  });
+
   it("sync yields route + search records via mocked driver", async () => {
     const dir = fs.mkdtempSync(path.join(os.tmpdir(), "amap-"));
     const dbPath = path.join(dir, "amap.db");

package/__tests__/whatsapp-adapter.test.js

@@ -43,8 +43,11 @@ describe("WhatsAppAdapter", () => {
     expect(a.dataDisclosure.legalGate).toBe(true);
   });
 
-  it("rejects missing account.phone", () => {
-    expect(() => new WhatsAppAdapter({ account: {} })).toThrow(/phone/);
+  it("no-arg ctor passes contract (2026-05-25 v0.6 — account.phone OPTIONAL for snapshot mode)", () => {
+    const a = new WhatsAppAdapter();
+    expect(assertAdapter(a).ok).toBe(true);
+    expect(a.capabilities).toContain("sync:snapshot");
+    expect(a.capabilities).toContain("sync:sqlite");
   });
 
   it("authenticate fails without DB", async () => {

package/lib/adapters/browser-history-chrome/chrome-db-reader.js

@@ -12,7 +12,16 @@ const os = require("node:os");
 // better-sqlite3 tracks Node's ABI 127 (test path). Whichever loads
 // without NODE_MODULE_VERSION mismatch wins. Both expose the same
 // Database class for unencrypted DBs.
+//
+// CRITICAL: must be lazy. Calling at module-load time means any require()
+// of this file (e.g. via PDH wiring's eager `require("@chainlesschain/
+// personal-data-hub/adapters/browser-history-chrome")`) throws synchronously
+// when both modules are absent/ABI-mismatched, killing the entire main
+// process before the BrowserHistoryChromeAdapter try/catch in wiring.js
+// can swallow it. See v5.0.3.87 crash + handbook trap #23.
+let _cachedDatabaseClass = null;
 function loadDatabase() {
+  if (_cachedDatabaseClass) return _cachedDatabaseClass;
   for (const mod of ["better-sqlite3-multiple-ciphers", "better-sqlite3"]) {
     let cls;
     try {
@@ -27,6 +36,7 @@ function loadDatabase() {
     try {
       const probe = new cls(":memory:");
       probe.close();
+      _cachedDatabaseClass = cls;
       return cls;
     } catch (_e) {
       // ABI mismatch — try next candidate
@@ -36,7 +46,6 @@ function loadDatabase() {
     "chrome-db-reader: neither better-sqlite3-multiple-ciphers nor better-sqlite3 loaded — both ABI-mismatched",
   );
 }
-const Database = loadDatabase();
 
 // WebKit timestamps are microseconds since 1601-01-01 UTC. Convert to
 // epoch-ms by shifting the epoch (11644473600 seconds × 1e6 µs/s).
@@ -168,6 +177,7 @@ function* readVisits(tmpPath, opts = {}) {
     : 0n;
   const limit = Number.isInteger(opts.limit) && opts.limit > 0 ? opts.limit : 200_000;
   const includeHidden = opts.includeHidden === true;
+  const Database = loadDatabase();
   const db = new Database(tmpPath, { readonly: true });
   try {
     // Bind sinceWk as a string — better-sqlite3 accepts BigInt only when