@chainlesschain/personal-data-hub 0.2.0 → 0.2.2

package/lib/adapters/system-data-android/adapter.js

@@ -0,0 +1,348 @@
+"use strict";
+
+// SystemDataAndroidAdapter — Plan A v0.1 (4-day slice, 2026-05-21).
+//
+// Reads a UI-produced JSON snapshot of the Android user's own ContentResolver
+// (contacts) and PackageManager (installed apps) and normalises it into PDH
+// entities. The snapshot is produced inside the Android app process (which
+// owns the JVM and can call ContentResolver / PackageManager directly); the
+// cc CLI subprocess then ingests that snapshot through this adapter.
+//
+// Why not extend PythonSidecarAdapter like the desktop `system-data`? Termux
+// does not ship a forensics-bridge sidecar and the data we read here is the
+// user's OWN device — no SQLite parsing or ADB pull is needed; ContentResolver
+// returns clean records. Keep it pure JS, zero sidecar.
+//
+// Out of scope for v0.1 (deferred):
+//   - SMS / call_log (need READ_SMS / READ_CALL_LOG and stricter legal gates)
+//   - Wifi (no ContentResolver, would need SystemConfiguration JNI)
+//   - cc-driven pull (would need a BoundService + Unix socket; v0.1 is UI-pushed)
+
+const { newId } = require("../../ids");
+const {
+  ENTITY_TYPES,
+  PERSON_SUBTYPES,
+  ITEM_SUBTYPES,
+  CAPTURED_BY,
+} = require("../../constants");
+
+const NAME = "system-data-android";
+const VERSION = "0.1.0";
+const SNAPSHOT_SCHEMA_VERSION = 1;
+
+// Stable per-source originalId — registry.putRawEvent rejects null originalId
+// with a NOT NULL constraint, surfacing as invalidCount += rawCount on the
+// SyncReport (real-device repro 2026-05-21: 1305 of 1305 raws "invalid"
+// despite all entities being written). Re-deriving the same key on each
+// sync also lets the raw_events store dedup naturally.
+function contactOriginalId(c) {
+  const k =
+    (c && typeof c.lookupKey === "string" && c.lookupKey.length > 0 && c.lookupKey) ||
+    (c && typeof c.displayName === "string" && c.displayName) ||
+    `unknown-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  return `android-contact:${k}`;
+}
+function appOriginalId(a) {
+  const k =
+    (a && typeof a.packageName === "string" && a.packageName) ||
+    `unknown-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  return `android-app:${k}`;
+}
+
+class SystemDataAndroidAdapter {
+  constructor(opts = {}) {
+    this.name = NAME;
+    this.version = VERSION;
+    this.capabilities = [
+      "sync:android-content-provider",
+      "sync:android-package-manager",
+    ];
+    this.extractMode = "device-pull";
+    this.rateLimits = { perDay: 24 };
+    this.dataDisclosure = {
+      fields: [
+        "contacts:displayName,phones,emails,starred,organization,photoUri",
+        "installed_apps:packageName,label,versionName,versionCode,firstInstallTime,lastUpdateTime,isSystem",
+      ],
+      sensitivity: "medium",
+      legalGate: false,
+      defaultInclude: { contacts: true, apps: true },
+    };
+
+    // _deps for test injection — mirrors the pattern in cli-dev.md so test
+    // harness can swap fs without resorting to vi.mock("fs") which doesn't
+    // intercept require() under inlined CJS. `bridgeProvider` is lazy because
+    // the cc-android-bridge module sits in `packages/cli` and is not always
+    // available in environments that load this adapter directly (e.g. desktop
+    // CLI building a snapshot ingest pipeline). Resolves to null when bridge
+    // is unreachable, in which case sync() falls back to inputPath mode.
+    this._deps = {
+      fs: require("node:fs"),
+      bridgeProvider: () => null,
+    };
+  }
+
+  // ─── PersonalDataAdapter contract ──────────────────────────────────────
+
+  async authenticate(ctx = {}) {
+    if (!ctx || typeof ctx.inputPath !== "string" || ctx.inputPath.length === 0) {
+      return {
+        ok: false,
+        reason: "INPUT_PATH_REQUIRED",
+        message:
+          "system-data-android requires opts.inputPath pointing to a snapshot JSON written by the Android app",
+      };
+    }
+    try {
+      this._deps.fs.accessSync(ctx.inputPath, this._deps.fs.constants.R_OK);
+    } catch (err) {
+      return {
+        ok: false,
+        reason: "INPUT_PATH_UNREADABLE",
+        message: `snapshot not readable at ${ctx.inputPath}: ${err.message}`,
+      };
+    }
+    return { ok: true, mode: "snapshot-file" };
+  }
+
+  async healthCheck() {
+    // The adapter itself is stateless — health is "always reachable" so long
+    // as a snapshot can be re-produced by the UI. Real device-status (whether
+    // the runtime permission was granted) lives in the Android-side UI.
+    return { ok: true, lastChecked: Date.now() };
+  }
+
+  async *sync(opts = {}) {
+    // Two ingestion modes (mutually exclusive — pick whichever fits the host):
+    //   1. snapshot mode: opts.inputPath points to JSON the Android UI wrote
+    //      (works on any host that can read the file — desktop or device).
+    //   2. bridge mode: opts.useBridge === true, _deps.bridgeProvider() returns
+    //      a live cc-android-bridge. Used inside in-APK cc when A6/A7 lands.
+    // If neither inputPath nor useBridge is set, bridge auto-engages when
+    // available (which only happens on Android with the JNI binding loaded,
+    // OR under CC_ANDROID_BRIDGE_OVERRIDE=1 in tests).
+    const wantBridge = opts.useBridge === true || (!opts.inputPath && this._bridgeAvailable());
+    if (wantBridge) {
+      yield* this._syncViaBridge(opts);
+      return;
+    }
+    if (!opts || typeof opts.inputPath !== "string") {
+      throw new Error(
+        "system-data-android.sync: needs opts.inputPath (snapshot mode) OR opts.useBridge=true (in-APK Android cc with cc-android-bridge.node loaded)"
+      );
+    }
+    yield* this._syncViaSnapshot(opts);
+  }
+
+  _bridgeAvailable() {
+    try {
+      const b = this._deps.bridgeProvider();
+      if (!b || typeof b.caps !== "function") return false;
+      const c = b.caps();
+      return c && c.available === true;
+    } catch (_e) {
+      return false;
+    }
+  }
+
+  async *_syncViaBridge(opts) {
+    const bridge = this._deps.bridgeProvider();
+    if (!bridge || typeof bridge.invoke !== "function") {
+      throw new Error(
+        "system-data-android.sync: useBridge=true but cc-android-bridge is not loaded (run inside in-APK cc, or set CC_ANDROID_BRIDGE_OVERRIDE=1 for tests)"
+      );
+    }
+    const includeContacts = opts.include?.contacts !== false;
+    const includeApps = opts.include?.apps !== false;
+    const limit = Number.isInteger(opts.limit) && opts.limit > 0 ? opts.limit : Infinity;
+    const capturedAt = Date.now();
+    let emitted = 0;
+
+    if (includeContacts) {
+      const res = await bridge.invoke("contacts.query", {
+        since: Number.isInteger(opts.since) ? opts.since : undefined,
+      });
+      const arr = Array.isArray(res) ? res : Array.isArray(res?.contacts) ? res.contacts : [];
+      for (const c of arr) {
+        if (emitted >= limit) return;
+        // originalId required by registry.putRawEvent (NOT NULL column); use
+        // the stable Android lookupKey when present, else displayName.
+        yield {
+          kind: "contact",
+          originalId: contactOriginalId(c),
+          capturedAt,
+          payload: c,
+        };
+        emitted += 1;
+      }
+    }
+
+    if (includeApps) {
+      const res = await bridge.invoke("app.list", { includeSystem: false });
+      const arr = Array.isArray(res) ? res : Array.isArray(res?.apps) ? res.apps : [];
+      for (const a of arr) {
+        if (emitted >= limit) return;
+        yield {
+          kind: "app",
+          originalId: appOriginalId(a),
+          capturedAt,
+          payload: a,
+        };
+        emitted += 1;
+      }
+    }
+  }
+
+  async *_syncViaSnapshot(opts) {
+    const raw = this._deps.fs.readFileSync(opts.inputPath, "utf-8");
+    const snapshot = JSON.parse(raw);
+    if (
+      !snapshot ||
+      typeof snapshot !== "object" ||
+      snapshot.schemaVersion !== SNAPSHOT_SCHEMA_VERSION
+    ) {
+      throw new Error(
+        `system-data-android.sync: snapshot schemaVersion mismatch (got ${snapshot && snapshot.schemaVersion}, expected ${SNAPSHOT_SCHEMA_VERSION})`
+      );
+    }
+    const capturedAt =
+      Number.isFinite(snapshot.snapshottedAt) && snapshot.snapshottedAt > 0
+        ? Math.floor(snapshot.snapshottedAt)
+        : Date.now();
+
+    const includeContacts = opts.include?.contacts !== false;
+    const includeApps = opts.include?.apps !== false;
+    const limit = Number.isInteger(opts.limit) && opts.limit > 0 ? opts.limit : Infinity;
+    let emitted = 0;
+
+    if (includeContacts && Array.isArray(snapshot.contacts)) {
+      for (const c of snapshot.contacts) {
+        if (emitted >= limit) return;
+        yield {
+          kind: "contact",
+          originalId: contactOriginalId(c),
+          capturedAt,
+          payload: c,
+        };
+        emitted += 1;
+      }
+    }
+
+    if (includeApps && Array.isArray(snapshot.apps)) {
+      for (const a of snapshot.apps) {
+        if (emitted >= limit) return;
+        yield {
+          kind: "app",
+          originalId: appOriginalId(a),
+          capturedAt,
+          payload: a,
+        };
+        emitted += 1;
+      }
+    }
+  }
+
+  normalize(raw) {
+    const ingestedAt = Date.now();
+    const source = (originalId) => ({
+      adapter: NAME,
+      adapterVersion: VERSION,
+      capturedAt: raw.capturedAt,
+      capturedBy: CAPTURED_BY.API,
+      originalId,
+    });
+
+    if (raw.kind === "contact") {
+      const p = raw.payload || {};
+      // lookupKey is Android's "stable across rename + edits" identifier; fall
+      // back to displayName only if missing, which lets future runs still dedup
+      // by name for the dataset where lookupKey is absent.
+      const stableKey =
+        (typeof p.lookupKey === "string" && p.lookupKey.length > 0 && p.lookupKey) ||
+        (typeof p.displayName === "string" && p.displayName) ||
+        `unknown-${raw.capturedAt}`;
+      const displayName =
+        typeof p.displayName === "string" && p.displayName.trim().length > 0
+          ? p.displayName.trim()
+          : "(无名联系人)";
+      const identifiers = {};
+      if (Array.isArray(p.phones) && p.phones.length > 0) {
+        identifiers.phone = p.phones.filter((x) => typeof x === "string" && x.length > 0);
+      }
+      if (Array.isArray(p.emails) && p.emails.length > 0) {
+        identifiers.email = p.emails.filter((x) => typeof x === "string" && x.length > 0);
+      }
+
+      const person = {
+        id: `person-android-${stableKey}`,
+        type: ENTITY_TYPES.PERSON,
+        subtype: PERSON_SUBTYPES.CONTACT,
+        names: [displayName],
+        ingestedAt,
+        source: source(`android-contact:${stableKey}`),
+      };
+      if (Object.keys(identifiers).length > 0) person.identifiers = identifiers;
+      if (typeof p.organization === "string" && p.organization.trim().length > 0) {
+        person.relation = p.organization.trim();
+      }
+      const extra = {};
+      if (typeof p.starred === "boolean") extra.starred = p.starred;
+      if (typeof p.photoUri === "string" && p.photoUri.length > 0) extra.photoUri = p.photoUri;
+      if (Object.keys(extra).length > 0) person.extra = extra;
+
+      return {
+        events: [],
+        persons: [person],
+        places: [],
+        items: [],
+        topics: [],
+      };
+    }
+
+    if (raw.kind === "app") {
+      const a = raw.payload || {};
+      const pkgName =
+        (typeof a.packageName === "string" && a.packageName) || `unknown.${newId()}`;
+      const label =
+        typeof a.label === "string" && a.label.trim().length > 0
+          ? a.label.trim()
+          : pkgName;
+
+      const item = {
+        id: `item-android-app-${pkgName}`,
+        type: ENTITY_TYPES.ITEM,
+        subtype: ITEM_SUBTYPES.OTHER,
+        name: label,
+        category: a.isSystem === true ? "system-app" : "user-app",
+        ingestedAt,
+        source: source(`android-app:${pkgName}`),
+        extra: {
+          kind: "installed_app",
+          packageName: pkgName,
+          versionName: typeof a.versionName === "string" ? a.versionName : null,
+          versionCode: Number.isInteger(a.versionCode) ? a.versionCode : null,
+          firstInstallTime: Number.isInteger(a.firstInstallTime) ? a.firstInstallTime : null,
+          lastUpdateTime: Number.isInteger(a.lastUpdateTime) ? a.lastUpdateTime : null,
+          isSystem: a.isSystem === true,
+        },
+      };
+
+      return {
+        events: [],
+        persons: [],
+        places: [],
+        items: [item],
+        topics: [],
+      };
+    }
+
+    throw new Error(`system-data-android.normalize: unknown raw.kind=${raw.kind}`);
+  }
+}
+
+module.exports = {
+  SystemDataAndroidAdapter,
+  SYSTEM_DATA_ANDROID_NAME: NAME,
+  SYSTEM_DATA_ANDROID_VERSION: VERSION,
+  SNAPSHOT_SCHEMA_VERSION,
+};

package/lib/adapters/system-data-android/index.js

@@ -0,0 +1,76 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const {
+  SystemDataAndroidAdapter,
+  SYSTEM_DATA_ANDROID_NAME,
+  SYSTEM_DATA_ANDROID_VERSION,
+  SNAPSHOT_SCHEMA_VERSION,
+} = require("./adapter");
+
+/**
+ * Path C — desktop-side helper. Given a hub instance + an inline snapshot
+ * payload from a mobile / browser client, write the snapshot to a staging
+ * file, run the adapter's snapshot-mode sync, then clean the staging file up.
+ *
+ * Centralizing here keeps the schemaVersion check + staging path convention
+ * + cleanup discipline in one place — IPC, WS, and P2P-mobile dispatch
+ * (3 separate transport adapters) all just call into this.
+ *
+ * @param {object} hub — hub-wiring output (must have `hubDir` + `registry.syncAdapter`)
+ * @param {object} snapshot — payload matching adapter.SNAPSHOT_SCHEMA_VERSION
+ * @param {object} [opts]
+ * @param {object} [opts.fs] — fs module override for tests (must expose
+ *   mkdirSync, writeFileSync, existsSync, unlinkSync)
+ * @returns {Promise<object>} SyncReport from registry.syncAdapter
+ */
+async function ingestSystemDataAndroidSnapshot(hub, snapshot, opts = {}) {
+  if (!hub || !hub.hubDir || !hub.registry) {
+    throw new Error(
+      "ingestSystemDataAndroidSnapshot: hub must expose hubDir + registry"
+    );
+  }
+  if (!snapshot || typeof snapshot !== "object") {
+    throw new Error(
+      "ingestSystemDataAndroidSnapshot: snapshot payload required"
+    );
+  }
+  if (snapshot.schemaVersion !== SNAPSHOT_SCHEMA_VERSION) {
+    throw new Error(
+      `ingestSystemDataAndroidSnapshot: schemaVersion ${snapshot.schemaVersion} != expected ${SNAPSHOT_SCHEMA_VERSION}`
+    );
+  }
+
+  const fsImpl = opts.fs || fs;
+  const stagingDir = path.join(hub.hubDir, "staging");
+  fsImpl.mkdirSync(stagingDir, { recursive: true });
+  const stagingPath = path.join(
+    stagingDir,
+    `system-data-android-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.json`
+  );
+  fsImpl.writeFileSync(stagingPath, JSON.stringify(snapshot), "utf-8");
+
+  try {
+    return await hub.registry.syncAdapter(SYSTEM_DATA_ANDROID_NAME, {
+      inputPath: stagingPath,
+    });
+  } finally {
+    // best-effort cleanup; failures shouldn't shadow the (possibly successful) sync
+    try {
+      if (fsImpl.existsSync(stagingPath)) {
+        fsImpl.unlinkSync(stagingPath);
+      }
+    } catch (_e) {
+      /* ignore */
+    }
+  }
+}
+
+module.exports = {
+  SystemDataAndroidAdapter,
+  SYSTEM_DATA_ANDROID_NAME,
+  SYSTEM_DATA_ANDROID_VERSION,
+  SNAPSHOT_SCHEMA_VERSION,
+  ingestSystemDataAndroidSnapshot,
+};

package/lib/adapters/wechat/bootstrap.js

@@ -0,0 +1,146 @@
+/**
+ * Phase 12.6.7 — WeChat adapter bootstrap helper.
+ *
+ * Glues env-probe (12.6.4) → KeyProvider choice (12.6.1) → WechatAdapter
+ * instantiation (12.6.5) into one entry point so the IPC / WS / CLI
+ * layers don't each have to recreate the wiring.
+ *
+ * Decision matrix (mirrors `env-probe.decide`):
+ *   - probe.suggestedKeyProvider === "md5"   → MD5KeyProvider
+ *   - probe.suggestedKeyProvider === "frida" → FridaKeyProvider
+ *   - probe.suggestedKeyProvider === "unsupported" → no adapter created;
+ *     caller gets `{ ok: false, probe, reason }` and is expected to surface
+ *     `probe.reasons[]` to the user.
+ *
+ * Caller may force a specific provider via `opts.keyProviderOverride`
+ * (e.g. `"md5"` on a real device that env-probe misclassified, useful for
+ * the rare 8.0+ install where the user has the MD5 path working). The
+ * override skips the suggestion but the probe still runs and is returned
+ * for transparency.
+ *
+ * Returns shape (also see __tests__/adapters/wechat-bootstrap.test.js):
+ *
+ *   { ok: true,  adapter, keyProvider, probe }
+ *   { ok: false, reason: "ENV_UNSUPPORTED" | "MD5_NEEDS_WECHAT_DATA_PATH"
+ *                       | "FRIDA_NEEDS_WXID" | "ADAPTER_CTOR_FAILED",
+ *     probe, message? }
+ *
+ * Test seams:
+ *   - opts._probe          inject pre-computed probe (skip exec)
+ *   - opts._md5Provider    inject pre-built MD5KeyProvider instance
+ *   - opts._fridaProvider  inject pre-built FridaKeyProvider instance
+ *   - opts._WechatAdapter  swap the adapter constructor (default: real)
+ */
+"use strict";
+
+const { WechatAdapter } = require("./wechat-adapter");
+const { MD5KeyProvider } = require("./key-providers/md5-key-provider");
+const { FridaKeyProvider } = require("./key-providers/frida-key-provider");
+const { probe: realProbe } = require("./env-probe");
+
+/**
+ * @param {object} opts
+ * @param {object} opts.account              `{ uin, wxid? }` — adapter sees uin
+ * @param {string} [opts.dbPath]             local path to pulled EnMicroMsg.db
+ * @param {string} [opts.wechatDataPath]     local pulled /data/data/com.tencent.mm
+ *                                            (required when MD5KeyProvider is chosen)
+ * @param {object} [opts.fridaOpts]          forwarded to FridaKeyProvider ctor
+ *                                            (deviceId / packageName / timeoutMs)
+ * @param {string} [opts.keyProviderOverride] "md5" | "frida" — force selection
+ * @param {Function} [opts.exec]             exec seam forwarded to env-probe
+ * @param {object} [opts._probe]             pre-computed probe (test seam)
+ * @param {object} [opts._md5Provider]       (test seam)
+ * @param {object} [opts._fridaProvider]     (test seam)
+ * @param {Function} [opts._WechatAdapter]   (test seam)
+ * @returns {Promise<object>}
+ */
+async function bootstrapWechatAdapter(opts = {}) {
+  if (!opts || typeof opts !== "object") {
+    throw new Error("bootstrapWechatAdapter: opts required");
+  }
+  if (!opts.account || !opts.account.uin) {
+    throw new Error("bootstrapWechatAdapter: opts.account.uin required");
+  }
+
+  const probe = opts._probe || (await realProbe({ exec: opts.exec }));
+  const chosen = opts.keyProviderOverride || probe.suggestedKeyProvider;
+
+  if (chosen === "unsupported") {
+    return {
+      ok: false,
+      reason: "ENV_UNSUPPORTED",
+      message: (probe.reasons || []).join("; ") || "env-probe could not pick a viable KeyProvider",
+      probe,
+    };
+  }
+
+  // Pick / build KeyProvider
+  let keyProvider;
+  if (chosen === "md5") {
+    if (opts._md5Provider) {
+      keyProvider = opts._md5Provider;
+    } else {
+      if (!opts.wechatDataPath) {
+        return {
+          ok: false,
+          reason: "MD5_NEEDS_WECHAT_DATA_PATH",
+          message: "MD5KeyProvider requires opts.wechatDataPath (pulled /data/data/com.tencent.mm/)",
+          probe,
+        };
+      }
+      keyProvider = new MD5KeyProvider({
+        wechatDataPath: opts.wechatDataPath,
+        uin: opts.account.uin,
+      });
+    }
+  } else if (chosen === "frida") {
+    if (opts._fridaProvider) {
+      keyProvider = opts._fridaProvider;
+    } else {
+      // FridaKeyProvider doesn't strictly need wxid, but we surface a
+      // clear error here when the wire-level account looks incomplete.
+      if (!opts.account.uin) {
+        return {
+          ok: false,
+          reason: "FRIDA_NEEDS_WXID",
+          message: "FridaKeyProvider expects opts.account.uin for downstream adapter wiring",
+          probe,
+        };
+      }
+      keyProvider = new FridaKeyProvider({
+        deviceId: (opts.fridaOpts && opts.fridaOpts.deviceId) || probe.device.serial || null,
+        packageName: (opts.fridaOpts && opts.fridaOpts.packageName) || "com.tencent.mm",
+        timeoutMs: (opts.fridaOpts && opts.fridaOpts.timeoutMs) || 30_000,
+      });
+    }
+  } else {
+    return {
+      ok: false,
+      reason: "UNKNOWN_KEY_PROVIDER",
+      message: `Unknown keyProvider "${chosen}"`,
+      probe,
+    };
+  }
+
+  // Instantiate adapter
+  const AdapterCtor = opts._WechatAdapter || WechatAdapter;
+  let adapter;
+  try {
+    adapter = new AdapterCtor({
+      account: opts.account,
+      dbPath: opts.dbPath || null,
+      keyProvider,
+    });
+  } catch (err) {
+    return {
+      ok: false,
+      reason: "ADAPTER_CTOR_FAILED",
+      message: err && err.message ? err.message : String(err),
+      probe,
+    };
+  }
+
+  return { ok: true, adapter, keyProvider, probe };
+}
+
+module.exports = { bootstrapWechatAdapter };

package/lib/adapters/wechat/content-parser.js

@@ -54,6 +54,10 @@ const APPMSG_SUBTYPES = {
   33: "miniprogram",
   36: "miniprogram",
   51: "channel-video",
+  // sjqz docs reference these higher subtype codes on newer WeChat builds —
+  // accept both for forward compatibility (post-Phase 12.6 audit).
+  2000: "transfer",
+  2001: "redpacket",
 };
 
 /**
@@ -225,10 +229,15 @@ function parseAppMsg(body) {
     url: url || null,
   };
 
-  // Redpacket-specific
-  if (appType === 21) {
+  // Redpacket-specific (accept both 21 and 2001 — see APPMSG_SUBTYPES)
+  if (appType === 21 || appType === 2001) {
     structured.redPacketTitle = title;
   }
+  // Transfer-specific
+  if (appType === 2000) {
+    structured.transferAmount =
+      extractTag(body, "feedesc") || extractTag(body, "pay_memo");
+  }
   // File-specific
   if (appType === 6) {
     structured.fileName = title;