@chainlesschain/personal-data-hub 0.3.0 → 0.3.6

package/lib/adapters/social-douyin-adb/db-extension.js

@@ -0,0 +1,281 @@
+"use strict";
+
+/**
+ * Phase 2a (Douyin C 路径 — 2026-05-25): douyin.pull-im-db ADB extension.
+ *
+ * Plugs into the `opts.extensions` slot of `createHostAdbBridge` /
+ * `createDesktopAdbBridge`. Pipeline:
+ *
+ *   1. ADB-ls `/data/data/com.ss.android.ugc.aweme/databases/` to find
+ *      `<uid>_im.db` (19-digit numeric uid prefix) — abrignoni DFIR pattern
+ *   2. ADB pull the .db cohort (main + -wal + -shm) via base64 streaming
+ *      (mirrors Bilibili Phase 1a — `su -c "base64 ..."` avoids MIUI FUSE
+ *      SELinux trap)
+ *   3. Verify each file's SQLite magic header before returning
+ *   4. Return `{tempPath, uid, walPath?, shmPath?, extractedAt}` for the
+ *      collector to feed into im-db-parser
+ *
+ * Bilibili Phase 1a uses base64 of a single file; Douyin needs the WAL/SHM
+ * cohort because the IM db is actively written by the chat thread —
+ * skipping WAL would lose the most-recent messages. We pull all 3 files
+ * and let the sqlite reader checkpoint them on open.
+ *
+ * Failure modes (throws on each; UI maps the typed error code to a banner):
+ *   - DOUYIN_NOT_INSTALLED — databases/ dir doesn't exist
+ *   - DOUYIN_NO_IM_DB — no `<uid>_im.db` matching the 19-digit pattern
+ *   - DOUYIN_MULTIPLE_USERS — >1 IM dbs (multi-account; need explicit uid)
+ *   - DOUYIN_NO_ROOT — su not available
+ *   - DOUYIN_PULL_FAILED — base64 stream error
+ *   - DOUYIN_NOT_SQLITE — pulled file lacks SQLite magic header
+ */
+
+const fs = require("node:fs");
+const path = require("node:path");
+const os = require("node:os");
+const crypto = require("node:crypto");
+
+const DOUYIN_DB_REMOTE_DIR =
+  "/data/data/com.ss.android.ugc.aweme/databases";
+
+const IM_DB_PATTERN = /^(\d{19})_im\.db$/;
+
+/**
+ * List candidate IM db filenames + uid via `adb shell su -c "ls databases/"`.
+ *
+ * Returns `{candidates: [{uid, fileName}], dirMissing: boolean}` so the
+ * caller can disambiguate "no Douyin installed" vs "Douyin installed but
+ * never logged in" vs "logged in to multiple accounts".
+ */
+async function listImDbs(adb, serial, opts) {
+  const adbOpts = { serial, timeoutMs: opts?.timeoutMs || 30_000 };
+  // ls returns "No such file or directory" to stdout when 2>/dev/null is
+  // appended (toybox ls behavior); we use a sentinel to disambiguate.
+  const lsOut = await adb(
+    [
+      "shell",
+      "su",
+      "-c",
+      `ls ${DOUYIN_DB_REMOTE_DIR} 2>/dev/null || echo __MISSING_DIR__`,
+    ],
+    adbOpts,
+  );
+  const lines = lsOut.replace(/\r/g, "").trim().split(/\n/);
+  if (lines.length === 1 && lines[0] === "__MISSING_DIR__") {
+    return { candidates: [], dirMissing: true };
+  }
+  const candidates = [];
+  for (const line of lines) {
+    const fileName = line.trim();
+    if (!fileName) continue;
+    const m = fileName.match(IM_DB_PATTERN);
+    if (m) {
+      candidates.push({ uid: m[1], fileName });
+    }
+  }
+  return { candidates, dirMissing: false };
+}
+
+/**
+ * Pull a single file via `su -c "base64 ..." | tr -d '\n\r'` streaming.
+ * Mirrors Bilibili Phase 1a:pullCookiesViaSu — same trap-mitigation reasons.
+ *
+ * Returns the decoded bytes as a Buffer. Throws on:
+ *  - ENOENT (file disappeared between ls and pull)
+ *  - empty base64 stream
+ *  - bad base64
+ *  - sqlite magic header missing
+ *  - decoded size < 1024 (truncation)
+ */
+async function pullFileViaSu(adb, serial, remotePath, opts) {
+  const adbOpts = { serial, timeoutMs: opts?.timeoutMs || 60_000 };
+  const b64 = await adb(
+    [
+      "shell",
+      "su",
+      "-c",
+      `base64 ${remotePath} 2>/dev/null | tr -d '\\n\\r'`,
+    ],
+    adbOpts,
+  );
+  const b64Clean = b64.replace(/[\r\n\t ]+/g, "");
+  if (b64Clean.length === 0) {
+    throw new Error(
+      `DOUYIN_PULL_FAILED: base64 stream of ${remotePath} returned 0 bytes (su exec may have silently failed)`,
+    );
+  }
+  let buf;
+  try {
+    buf = Buffer.from(b64Clean, "base64");
+  } catch (e) {
+    throw new Error(
+      `DOUYIN_PULL_FAILED: base64 decode failed for ${remotePath}: ${e.message || String(e)}`,
+    );
+  }
+  return buf;
+}
+
+/**
+ * Factory: returns an extension handler suitable for the `opts.extensions`
+ * map of `createHostAdbBridge` / `createDesktopAdbBridge`.
+ *
+ *   const ext = createDouyinDbExtension();
+ *   const bridge = createHostAdbBridge({ extensions: { "douyin.pull-im-db": ext } });
+ *   const { tempPath, uid } = await bridge.invoke("douyin.pull-im-db");
+ *
+ * Params (all optional):
+ *   - uid: prefer this specific uid when multiple `<uid>_im.db` exist on
+ *     the device (defaults to throwing DOUYIN_MULTIPLE_USERS so the user
+ *     picks one explicitly)
+ *
+ * @param {{timeoutMs?: number, onCleanupFailed?: (path: string) => void}} [factoryOpts]
+ * @returns {(params: object, ctx: object) => Promise<{tempPath, uid, walPath?, shmPath?, extractedAt}>}
+ */
+function createDouyinDbExtension(factoryOpts = {}) {
+  const timeoutMs = factoryOpts.timeoutMs || 60_000;
+  const onCleanupFailed = factoryOpts.onCleanupFailed || (() => {});
+
+  return async function douyinPullImDbHandler(params, ctx) {
+    if (
+      !ctx ||
+      typeof ctx.adb !== "function" ||
+      typeof ctx.pickDevice !== "function"
+    ) {
+      throw new TypeError(
+        "douyin.pull-im-db: ctx must provide {adb, pickDevice}",
+      );
+    }
+    const serial = await ctx.pickDevice();
+
+    // Step 0: probe su availability — clearer error than "ls failed".
+    const idOut = await ctx.adb(
+      ["shell", "su", "-c", "id -u"],
+      { serial, timeoutMs },
+    );
+    const idLine = idOut.replace(/\r+$/gm, "").trim();
+    if (idLine !== "0" && !idLine.includes("uid=0")) {
+      throw new Error(
+        `DOUYIN_NO_ROOT: phone isn't rooted (su -c id -u returned \`${idLine.substring(0, 60)}\`). Douyin release APK isn't debuggable, so root is required to read /data/data/com.ss.android.ugc.aweme/databases/.`,
+      );
+    }
+
+    // Step 1: discover candidate IM dbs.
+    const { candidates, dirMissing } = await listImDbs(ctx.adb, serial, {
+      timeoutMs,
+    });
+    if (dirMissing) {
+      throw new Error(
+        "DOUYIN_NOT_INSTALLED: " +
+          DOUYIN_DB_REMOTE_DIR +
+          " does not exist. Install Douyin App on the phone, then retry.",
+      );
+    }
+    if (candidates.length === 0) {
+      throw new Error(
+        "DOUYIN_NO_IM_DB: no `<19-digit-uid>_im.db` found in databases/. Open the Douyin App + log in once + open any chat thread to materialize the IM database, then retry.",
+      );
+    }
+    let chosen;
+    const requestedUid = params && typeof params.uid === "string" ? params.uid : null;
+    if (requestedUid) {
+      chosen = candidates.find((c) => c.uid === requestedUid);
+      if (!chosen) {
+        throw new Error(
+          `DOUYIN_UID_NOT_FOUND: requested uid=${requestedUid} not in ${JSON.stringify(candidates.map((c) => c.uid))}`,
+        );
+      }
+    } else if (candidates.length === 1) {
+      chosen = candidates[0];
+    } else {
+      throw new Error(
+        `DOUYIN_MULTIPLE_USERS: multiple IM dbs found (${candidates.map((c) => c.uid).join(", ")}). Pass {uid: "<19-digit>"} to disambiguate.`,
+      );
+    }
+
+    // Step 2: pull the cohort (main + -wal + -shm).
+    // Brignoni's article notes the WAL sibling holds the most-recent
+    // messages — Douyin commits to WAL on send/receive but only
+    // checkpoints back to main on app idle. Skipping WAL loses the last
+    // ~hour of chat. Best-effort: WAL/SHM may not exist if app just
+    // checkpointed.
+    const remoteDb = `${DOUYIN_DB_REMOTE_DIR}/${chosen.fileName}`;
+    const remoteWal = remoteDb + "-wal";
+    const remoteShm = remoteDb + "-shm";
+
+    const tmpDir = os.tmpdir();
+    const tmpId = crypto.randomUUID();
+    const tempPath = path.join(tmpDir, `cc-douyin-im-${tmpId}.db`);
+    let walPath = null;
+    let shmPath = null;
+
+    const dbBuf = await pullFileViaSu(ctx.adb, serial, remoteDb, { timeoutMs });
+    // Magic check on the main file.
+    if (dbBuf.length < 1024) {
+      throw new Error(
+        `DOUYIN_PULL_FAILED: decoded ${remoteDb} is only ${dbBuf.length} bytes — expected ≥4KB sqlite. Possible MIUI silent su fail.`,
+      );
+    }
+    const magic = dbBuf.subarray(0, 16).toString("latin1");
+    if (!magic.startsWith("SQLite format 3")) {
+      throw new Error(
+        `DOUYIN_NOT_SQLITE: ${remoteDb} decoded but lacks 'SQLite format 3' magic header. Got: ${dbBuf.subarray(0, 16).toString("hex")}`,
+      );
+    }
+    fs.writeFileSync(tempPath, dbBuf);
+
+    // Best-effort: pull WAL+SHM if present. Errors here just skip — main
+    // db parses fine without them, only loses recent messages.
+    try {
+      const walBuf = await pullFileViaSu(ctx.adb, serial, remoteWal, {
+        timeoutMs,
+      });
+      if (walBuf.length > 0) {
+        walPath = path.join(tmpDir, `cc-douyin-im-${tmpId}.db-wal`);
+        fs.writeFileSync(walPath, walBuf);
+      }
+    } catch (_e) {
+      // No WAL — typical if app idle for >a few hours
+    }
+    try {
+      const shmBuf = await pullFileViaSu(ctx.adb, serial, remoteShm, {
+        timeoutMs,
+      });
+      if (shmBuf.length > 0) {
+        shmPath = path.join(tmpDir, `cc-douyin-im-${tmpId}.db-shm`);
+        fs.writeFileSync(shmPath, shmBuf);
+      }
+    } catch (_e) {
+      // No SHM — same as WAL
+    }
+
+    return {
+      tempPath,
+      uid: chosen.uid,
+      walPath,
+      shmPath,
+      extractedAt: Date.now(),
+      // Caller is responsible for cleanup. We expose the cleanup helper
+      // separately so the caller can run it in a finally block.
+      cleanup() {
+        for (const p of [tempPath, walPath, shmPath]) {
+          if (!p) continue;
+          try {
+            fs.unlinkSync(p);
+          } catch (_e) {
+            onCleanupFailed(p);
+          }
+        }
+      },
+    };
+  };
+}
+
+module.exports = {
+  createDouyinDbExtension,
+  DOUYIN_DB_REMOTE_DIR,
+  IM_DB_PATTERN,
+  // Exposed for tests
+  _internals: {
+    listImDbs,
+    pullFileViaSu,
+  },
+};

package/lib/adapters/social-douyin-adb/im-db-parser.js

@@ -0,0 +1,287 @@
+"use strict";
+
+/**
+ * Phase 2a (Douyin C 路径 — 2026-05-25): Douyin IM sqlite parser.
+ *
+ * Parses the Douyin Android App's per-user IM sqlite:
+ *   /data/data/com.ss.android.ugc.aweme/databases/<uid>_im.db
+ *
+ * Where `<uid>` is the 19-digit numeric Douyin UID (matches what the app
+ * shows in passport/account/info/v2 as `user_id`, not the secUid).
+ *
+ * Schema reference: Alexis Brignoni's TIKTOK DFIR SQL repo
+ *   https://github.com/abrignoni/DFIR-SQL-Query-Repo/blob/master/Android/TIKTOK/TikTokMessages.sql
+ *
+ * Two tables we parse:
+ *
+ *   msg
+ *     sender         INTEGER  — sender UID (numeric, matches DB filename uid for self-sent)
+ *     created_time   INTEGER  — Unix epoch milliseconds
+ *     content        TEXT     — JSON: {text, display_name, url:{url_list:[...]}}
+ *     read_status    INTEGER
+ *     local_info     TEXT
+ *     conversation_id TEXT    — peer thread identifier
+ *
+ *   SIMPLE_USER  (contacts cache; mutual-follow visible)
+ *     UID            INTEGER
+ *     short_id       INTEGER
+ *     name           TEXT
+ *     avatar_url     TEXT
+ *     follow_status  INTEGER  — 0/1/2 (none/following/mutual)
+ *
+ * Both tables are **unencrypted SQLite**. No SQLCipher. Douyin (and global
+ * TikTok) stores its IM db in plaintext on Android per multiple academic
+ * forensic studies (Brignoni 2018, ACM ARES 2020). This is the key
+ * differentiator from WeChat/QQ which need frida hooks for the key.
+ *
+ * What this parser DOES NOT do:
+ *  - Decrypt encrypted message attachments (separate `attachment_<id>` files
+ *    in the same dir; not in scope for v0.1)
+ *  - Resolve sender UID → nickname (would need a JOIN to SIMPLE_USER; we
+ *    emit both tables separately so the consumer can correlate)
+ *  - Sticker / voice / video message content (the content JSON has type
+ *    discriminators we ignore — only `text` is extracted; other types
+ *    yield empty `text` field with the raw payload preserved)
+ *
+ * Test seam: callers can inject a synthetic `_databaseClass` to bypass the
+ * dual-load probe (Phase 1a chromium-cookies-reader pattern).
+ */
+
+/**
+ * Dual-load: prefers bs3mc (Electron ABI 140 runtime), falls back to plain
+ * better-sqlite3 (Node ABI 127 test path). Same pattern as
+ * social-bilibili-adb/chromium-cookies-reader.js.
+ */
+function loadDatabaseClass() {
+  for (const mod of ["better-sqlite3-multiple-ciphers", "better-sqlite3"]) {
+    let cls;
+    try {
+      // eslint-disable-next-line global-require
+      cls = require(mod);
+    } catch (_e) {
+      continue;
+    }
+    try {
+      const probe = new cls(":memory:");
+      probe.close();
+      return cls;
+    } catch (_e) {
+      // ABI mismatch — try next
+    }
+  }
+  throw new Error(
+    "douyin-im-db-parser: neither better-sqlite3-multiple-ciphers nor better-sqlite3 loaded — both ABI-mismatched",
+  );
+}
+
+/**
+ * Parse a content blob (TEXT column) for the user-visible text. The blob
+ * is JSON for most modern Douyin versions, but some legacy rows have the
+ * text directly. We try JSON first, fall back to the raw string.
+ *
+ * @param {string} blob raw content column value
+ * @returns {string|null} extracted text, or null if blob is empty/unparseable
+ */
+function extractTextFromContent(blob) {
+  if (typeof blob !== "string" || blob.length === 0) return null;
+  try {
+    const parsed = JSON.parse(blob);
+    if (parsed && typeof parsed === "object") {
+      // Modern shape: {text: "...", display_name: "...", url: {url_list: [...]}}
+      if (typeof parsed.text === "string") return parsed.text;
+      // Some versions wrap text in `content` nested
+      if (parsed.content && typeof parsed.content.text === "string") return parsed.content.text;
+    }
+  } catch (_e) {
+    // Not JSON — return the raw value (could be a legacy plaintext row)
+    return blob;
+  }
+  return null;
+}
+
+/**
+ * Parse the msg + SIMPLE_USER tables from a Douyin IM sqlite at [dbPath].
+ *
+ * Returns `{ messages, contacts, diagnostic }` where:
+ *   - messages: Array<{senderUid, conversationId, createdTimeMs, text, readStatus, contentBlob}>
+ *   - contacts: Array<{uid, shortId, name, avatarUrl, followStatus}>
+ *   - diagnostic: {messageCount, contactCount, hadMsgTable, hadSimpleUserTable}
+ *
+ * If either table is missing (older Douyin version, or non-IM db opened
+ * by mistake), the missing array is empty + `hadXxxTable=false` so the
+ * caller can warn the user. Throws only when the db file itself isn't
+ * openable (file corrupted / wrong magic header).
+ *
+ * @param {string} dbPath  absolute path to the IM sqlite db
+ * @param {{_databaseClass?: any, limitMessages?: number, limitContacts?: number}} [opts]
+ * @returns {{messages: Array, contacts: Array, diagnostic: object}}
+ */
+function parseImDb(dbPath, opts = {}) {
+  if (typeof dbPath !== "string" || dbPath.length === 0) {
+    throw new TypeError("parseImDb: dbPath must be a non-empty string");
+  }
+  const limitMessages =
+    Number.isInteger(opts.limitMessages) && opts.limitMessages > 0
+      ? opts.limitMessages
+      : 10_000;
+  const limitContacts =
+    Number.isInteger(opts.limitContacts) && opts.limitContacts > 0
+      ? opts.limitContacts
+      : 5_000;
+  const Database = opts._databaseClass || loadDatabaseClass();
+  const db = new Database(dbPath, { readonly: true });
+  const out = {
+    messages: [],
+    contacts: [],
+    diagnostic: {
+      messageCount: 0,
+      contactCount: 0,
+      hadMsgTable: false,
+      hadSimpleUserTable: false,
+    },
+  };
+  try {
+    // ─── msg table ───────────────────────────────────────────────────────
+    const msgTableInfo = trySelect(
+      db,
+      "PRAGMA table_info(msg)",
+    );
+    if (Array.isArray(msgTableInfo) && msgTableInfo.length > 0) {
+      out.diagnostic.hadMsgTable = true;
+      const columns = new Set(msgTableInfo.map((r) => r.name));
+      // Defensive column picker — Douyin app versions add/drop columns.
+      // We need: sender + created_time + content. Other fields nice-to-have.
+      const senderCol = pickCol(columns, ["sender", "from_user_id", "uid"]);
+      const timeCol = pickCol(columns, [
+        "created_time",
+        "create_time",
+        "created_at",
+      ]);
+      const contentCol = pickCol(columns, ["content", "message_content"]);
+      const convCol = pickCol(columns, [
+        "conversation_id",
+        "conv_id",
+        "session_id",
+      ]);
+      const readCol = pickCol(columns, ["read_status", "read", "is_read"]);
+      if (senderCol && timeCol && contentCol) {
+        const sql =
+          `SELECT ${senderCol} AS sender, ${timeCol} AS createdTime, ${contentCol} AS content` +
+          (convCol ? `, ${convCol} AS conversationId` : "") +
+          (readCol ? `, ${readCol} AS readStatus` : "") +
+          ` FROM msg ORDER BY ${timeCol} DESC LIMIT ${limitMessages}`;
+        const rows = trySelect(db, sql) || [];
+        for (const r of rows) {
+          const createdTimeMs = normalizeEpochMs(r.createdTime);
+          out.messages.push({
+            senderUid:
+              typeof r.sender === "number"
+                ? String(r.sender)
+                : r.sender != null
+                  ? String(r.sender)
+                  : null,
+            conversationId: r.conversationId ? String(r.conversationId) : null,
+            createdTimeMs,
+            text: extractTextFromContent(r.content),
+            readStatus:
+              typeof r.readStatus === "number" ? r.readStatus : null,
+            contentBlob: typeof r.content === "string" ? r.content : null,
+          });
+        }
+        out.diagnostic.messageCount = out.messages.length;
+      }
+    }
+
+    // ─── SIMPLE_USER table ───────────────────────────────────────────────
+    const userTableInfo = trySelect(
+      db,
+      "PRAGMA table_info(SIMPLE_USER)",
+    );
+    if (Array.isArray(userTableInfo) && userTableInfo.length > 0) {
+      out.diagnostic.hadSimpleUserTable = true;
+      const columns = new Set(userTableInfo.map((r) => r.name));
+      const uidCol = pickCol(columns, ["UID", "uid", "user_id"]);
+      const shortIdCol = pickCol(columns, ["short_id", "shortId", "ShortId"]);
+      const nameCol = pickCol(columns, ["name", "nick_name", "nickname"]);
+      const avatarCol = pickCol(columns, ["avatar_url", "avatarUrl", "avatar"]);
+      const followCol = pickCol(columns, [
+        "follow_status",
+        "followStatus",
+        "follow_state",
+      ]);
+      if (uidCol) {
+        const fields = [`${uidCol} AS uid`];
+        if (shortIdCol) fields.push(`${shortIdCol} AS shortId`);
+        if (nameCol) fields.push(`${nameCol} AS name`);
+        if (avatarCol) fields.push(`${avatarCol} AS avatarUrl`);
+        if (followCol) fields.push(`${followCol} AS followStatus`);
+        const sql = `SELECT ${fields.join(", ")} FROM SIMPLE_USER LIMIT ${limitContacts}`;
+        const rows = trySelect(db, sql) || [];
+        for (const r of rows) {
+          out.contacts.push({
+            uid: r.uid != null ? String(r.uid) : null,
+            shortId: r.shortId != null ? String(r.shortId) : null,
+            name: r.name || null,
+            avatarUrl: r.avatarUrl || null,
+            followStatus:
+              typeof r.followStatus === "number" ? r.followStatus : null,
+          });
+        }
+        out.diagnostic.contactCount = out.contacts.length;
+      }
+    }
+  } finally {
+    db.close();
+  }
+  return out;
+}
+
+/**
+ * Normalize various epoch units to ms. Douyin sometimes writes seconds,
+ * sometimes microseconds, sometimes ms. Heuristic: 13-digit = ms,
+ * 10-digit = seconds, 16-digit = microseconds.
+ */
+function normalizeEpochMs(v) {
+  if (typeof v !== "number" || !Number.isFinite(v) || v <= 0) return null;
+  // > 1e16 µs → / 1000
+  if (v > 1e15) return Math.floor(v / 1000);
+  // > 1e12 ms → keep
+  if (v > 1e12) return Math.floor(v);
+  // <= 1e12 seconds → × 1000
+  return Math.floor(v * 1000);
+}
+
+/**
+ * Try a SELECT; return the row array on success or null on any error
+ * (missing table / syntax error / driver throw). Mirrors social-bilibili
+ * adapter.js:trySelect.
+ */
+function trySelect(db, sql) {
+  try {
+    return db.prepare(sql).all();
+  } catch (_e) {
+    return null;
+  }
+}
+
+/**
+ * Return the first column in [candidates] that exists in [columns], or
+ * null. Used to handle Douyin's schema drift across versions.
+ */
+function pickCol(columns, candidates) {
+  for (const c of candidates) {
+    if (columns.has(c)) return c;
+  }
+  return null;
+}
+
+module.exports = {
+  parseImDb,
+  // Exposed for tests
+  _internals: {
+    loadDatabaseClass,
+    extractTextFromContent,
+    normalizeEpochMs,
+    pickCol,
+  },
+};

package/lib/adapters/social-douyin-adb/index.js

@@ -0,0 +1,57 @@
+"use strict";
+
+/**
+ * social-douyin-adb — Phase 2 (Douyin C 路径) entry.
+ *
+ * Phase 2a (this commit) — desktop ADB-based IM db extraction:
+ *   - douyin.pull-im-db extension     pulls <uid>_im.db cohort to host
+ *   - parseImDb                        parse msg + SIMPLE_USER tables
+ *   - buildSnapshot                    → schemaVersion=1 events JSON
+ *   - collect / collectAndSync         orchestrator
+ *
+ * Phase 2b (next) — Android Kotlin B path (in-APK root):
+ *   - reuse Phase B0 LocalRootCollector / BaseRootCredentialsStore /
+ *     RootShellRunner / DbCohortCopier scaffold
+ *   - libmsaoaidsec.so frida bypass for the anti-debug TracerPid check
+ *
+ * Pipeline (C path):
+ *   bridge.invoke("douyin.pull-im-db")
+ *     → parseImDb(tempPath)
+ *     → buildSnapshot + writeSnapshotJson
+ *     → registry.syncAdapter("social-douyin", { inputPath })
+ *
+ * Reuses the existing `social-douyin` adapter's snapshot mode — no 2nd
+ * adapter, same vault schema / dedup / event types. Phase 2a extended
+ * VALID_SNAPSHOT_KINDS in social-douyin/index.js to include `message` +
+ * `contact` for the abrignoni-DFIR-parsed IM tables.
+ */
+
+const {
+  createDouyinDbExtension,
+  DOUYIN_DB_REMOTE_DIR,
+  IM_DB_PATTERN,
+} = require("./db-extension");
+const { parseImDb } = require("./im-db-parser");
+const {
+  buildSnapshot,
+  writeSnapshotJson,
+  cleanupSnapshotJson,
+  SNAPSHOT_SCHEMA_VERSION,
+} = require("./snapshot-builder");
+const { collect, collectAndSync } = require("./collector");
+
+module.exports = {
+  // Extension factory (wiring registers this on the bridge)
+  createDouyinDbExtension,
+  DOUYIN_DB_REMOTE_DIR,
+  IM_DB_PATTERN,
+  // Parser + builder (also exposed for advanced callers / tests)
+  parseImDb,
+  buildSnapshot,
+  writeSnapshotJson,
+  cleanupSnapshotJson,
+  SNAPSHOT_SCHEMA_VERSION,
+  // Collector orchestrator
+  collect,
+  collectAndSync,
+};