@chainlesschain/personal-data-hub 0.3.1 → 0.3.7

package/lib/adapters/social-weibo-adb/api-client.js

@@ -0,0 +1,281 @@
+"use strict";
+
+/**
+ * Phase 3a (Weibo C 路径 — 2026-05-25): Node-side WeiboApiClient.
+ *
+ * Byte-parity port of
+ * `android-app/.../pdh/social/weibo/WeiboApiClient.kt` for the desktop
+ * PC + ADB path. Same m.weibo.cn endpoints, same headers, same JSON
+ * parse shape. Lockstep with the Kotlin version — if a real-device trap
+ * surfaces fix both sides.
+ *
+ * **Key differences from Bilibili Phase 1b**:
+ *  1. **No WBI signing** — m.weibo.cn mobile API requires cookie + UA +
+ *     XHR header but no signature. Simpler client, no /nav handshake.
+ *  2. **UID via /api/config** — Weibo cookie has no DedeUserID equivalent;
+ *     fetchUid() must do an HTTP roundtrip and persist the result.
+ *  3. **Time field is ISO 8601** — "Sun Jan 12 13:45:00 +0800 2026"
+ *     format (not unix seconds like Bilibili). Java's SimpleDateFormat
+ *     parses it; Node's Date can too once we know the format.
+ *  4. **Timeline endpoint via containerid** — user posts go through
+ *     /api/container/getIndex?containerid=107603<uid>, not a dedicated
+ *     /api/posts.
+ *  5. **Anti-bot signal**: missing `X-Requested-With: XMLHttpRequest` +
+ *     `MWeibo-Pwa: 1` → 30x redirect to login HTML.
+ *
+ * 4 endpoints:
+ *   - config     /api/config (fetchUid + login state check)
+ *   - posts      /api/container/getIndex?type=uid&value=<uid>&containerid=107603<uid>
+ *   - favourites /api/favorites?page=1
+ *   - follows    /api/friendships/friends?uid=<uid>&page=1
+ *
+ * Errors don't throw — endpoints that fail return [] and lastErrorCode +
+ * lastErrorMessage surface the cause for partial-result diagnostics.
+ */
+
+const DEFAULT_BASE_URL = "https://m.weibo.cn/";
+
+// Pinned Chrome 120 mobile UA — must look like a browser, default
+// `node-fetch/x.y.z` returns -100 silentband.
+const BROWSER_UA =
+  "Mozilla/5.0 (Linux; Android 14; ChainlessChain) AppleWebKit/537.36 " +
+  "(KHTML, like Gecko) Chrome/120.0.0.0 Mobile Safari/537.36";
+
+const BROWSER_HEADERS = Object.freeze({
+  "User-Agent": BROWSER_UA,
+  Referer: "https://m.weibo.cn/",
+  Accept: "application/json, text/plain, */*",
+  "Accept-Language": "zh-CN,zh;q=0.9,en;q=0.8",
+  // m.weibo.cn anti-bot: missing these → HTML redirect, not JSON
+  "X-Requested-With": "XMLHttpRequest",
+  "MWeibo-Pwa": "1",
+});
+
+/**
+ * Parse Weibo's ISO-8601-ish timestamp.
+ *   "Sun Jan 12 13:45:00 +0800 2026" → epoch ms
+ *   "1716383021"                     → epoch ms (× 1000 since it's < 1e12)
+ *   "1716383021000"                  → epoch ms (verbatim)
+ *
+ * Mirrors WeiboApiClient.kt:parseWeiboTime.
+ */
+function parseWeiboTime(raw) {
+  if (typeof raw !== "string" || raw.length === 0) return 0;
+  // Digits-only fallback — Weibo occasionally serves unix-seconds verbatim
+  if (/^\d+$/.test(raw)) {
+    const n = parseInt(raw, 10);
+    return n > 1e12 ? n : n * 1000;
+  }
+  // "EEE MMM dd HH:mm:ss Z yyyy" — JS Date.parse handles this in V8 / Node.
+  const t = Date.parse(raw);
+  return Number.isFinite(t) ? t : 0;
+}
+
+/**
+ * Strip HTML from Weibo's `text` field (contains <a>, <span>, &nbsp; etc.).
+ * Mirrors WeiboApiClient.kt:stripHtml.
+ */
+function stripHtml(raw) {
+  if (typeof raw !== "string" || raw.length === 0) return "";
+  return raw
+    .replace(/<[^>]+>/g, "")
+    .replace(/&nbsp;/g, " ")
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .trim();
+}
+
+class WeiboApiClient {
+  constructor(opts = {}) {
+    this.baseUrl = opts.baseUrl || DEFAULT_BASE_URL;
+    if (!this.baseUrl.endsWith("/")) this.baseUrl += "/";
+    this._fetch = opts.fetch || globalThis.fetch;
+    if (typeof this._fetch !== "function") {
+      throw new Error(
+        "WeiboApiClient: fetch not available — pass opts.fetch or run on Node 18+",
+      );
+    }
+    this.lastErrorCode = 0;
+    this.lastErrorMessage = null;
+  }
+
+  /**
+   * GET <url> with browser-like headers. Mirrors Kotlin doGetJson —
+   * including the non-JSON-body check (Weibo redirects to login HTML
+   * when cookie expired).
+   */
+  async _doGetJson(url, cookie) {
+    try {
+      const resp = await this._fetch(url.toString(), {
+        method: "GET",
+        headers: { ...BROWSER_HEADERS, Cookie: cookie },
+      });
+      const body = await resp.text();
+      if (!resp.ok) {
+        this._setLastError(resp.status, `HTTP ${resp.status}`);
+        return null;
+      }
+      const trimmed = body.trimStart();
+      if (!trimmed.startsWith("{")) {
+        // Login redirect / anti-bot HTML — cookie expired or anti-spider hit
+        this._setLastError(-4, "non-json (cookie expired?)");
+        return null;
+      }
+      let obj;
+      try {
+        obj = JSON.parse(body);
+      } catch (e) {
+        this._setLastError(-3, "parse: " + (e.message || String(e)));
+        return null;
+      }
+      const ok = typeof obj.ok === "number" ? obj.ok : 1;
+      if (ok !== 1) {
+        this._setLastError(ok, (obj.msg || "").toString());
+        return null;
+      }
+      this._clearLastError();
+      return obj;
+    } catch (e) {
+      this._setLastError(-2, "IO: " + (e.message || String(e)));
+      return null;
+    }
+  }
+
+  _setLastError(code, message) {
+    this.lastErrorCode = code;
+    this.lastErrorMessage = message;
+  }
+  _clearLastError() {
+    this.lastErrorCode = 0;
+    this.lastErrorMessage = null;
+  }
+
+  /**
+   * Fetch /api/config to get UID + validate login state. Returns numeric
+   * UID on success, null on failure (cookie expired / not logged in).
+   * Mirrors WeiboApiClient.kt:fetchUid.
+   */
+  async fetchUid(cookie) {
+    const url = new URL("api/config", this.baseUrl);
+    const obj = await this._doGetJson(url, cookie);
+    if (!obj) return null;
+    const data = obj.data || {};
+    if (!data.login) return null;
+    const uidStr = data.uid;
+    const uid = parseInt(uidStr, 10);
+    return Number.isFinite(uid) && uid > 0 ? uid : null;
+  }
+
+  /**
+   * Fetch the user's own posts (timeline). Mirrors fetchPosts —
+   * containerid=107603<uid> is the magic "user's own mblog" container.
+   */
+  async fetchPosts(cookie, uid, opts = {}) {
+    const limit = Number.isInteger(opts.limit) && opts.limit > 0 ? opts.limit : 100;
+    const containerid = `107603${uid}`;
+    const url = new URL("api/container/getIndex", this.baseUrl);
+    url.searchParams.set("type", "uid");
+    url.searchParams.set("value", String(uid));
+    url.searchParams.set("containerid", containerid);
+    const obj = await this._doGetJson(url, cookie);
+    if (!obj) return [];
+    const data = obj.data || {};
+    const cards = Array.isArray(data.cards) ? data.cards : [];
+    const out = [];
+    for (const card of cards) {
+      if (out.length >= limit) break;
+      if (!card || card.card_type !== 9) continue; // card_type=9 = mblog
+      const blog = card.mblog;
+      if (!blog) continue;
+      const mid = (blog.mid && String(blog.mid)) || (blog.id && String(blog.id));
+      if (!mid) continue;
+      out.push({
+        mid,
+        text: stripHtml(blog.text),
+        createdAt: parseWeiboTime(blog.created_at),
+        source: blog.source || null,
+        repostsCount: typeof blog.reposts_count === "number" ? blog.reposts_count : 0,
+        commentsCount:
+          typeof blog.comments_count === "number" ? blog.comments_count : 0,
+        likesCount:
+          typeof blog.attitudes_count === "number" ? blog.attitudes_count : 0,
+        picCount: typeof blog.pic_num === "number" ? blog.pic_num : 0,
+      });
+    }
+    return out;
+  }
+
+  /** Mirrors fetchFavourites. */
+  async fetchFavourites(cookie, opts = {}) {
+    const limit = Number.isInteger(opts.limit) && opts.limit > 0 ? opts.limit : 100;
+    const url = new URL("api/favorites", this.baseUrl);
+    url.searchParams.set("page", "1");
+    const obj = await this._doGetJson(url, cookie);
+    if (!obj) return [];
+    const data = obj.data || {};
+    const favs = Array.isArray(data.favorites) ? data.favorites : [];
+    const out = [];
+    for (let i = 0; i < Math.min(limit, favs.length); i++) {
+      const fav = favs[i];
+      if (!fav) continue;
+      const status = fav.status;
+      if (!status) continue;
+      const mid = (status.mid && String(status.mid)) || (status.id && String(status.id));
+      if (!mid) continue;
+      const author = status.user || {};
+      const favAt =
+        parseWeiboTime(fav.favorited_time) ||
+        parseWeiboTime(status.created_at) ||
+        0;
+      out.push({
+        mid,
+        text: stripHtml(status.text),
+        favAt,
+        authorScreenName: author.screen_name || null,
+      });
+    }
+    return out;
+  }
+
+  /** Mirrors fetchFollows. */
+  async fetchFollows(cookie, uid, opts = {}) {
+    const limit = Number.isInteger(opts.limit) && opts.limit > 0 ? opts.limit : 200;
+    const url = new URL("api/friendships/friends", this.baseUrl);
+    url.searchParams.set("uid", String(uid));
+    url.searchParams.set("page", "1");
+    const obj = await this._doGetJson(url, cookie);
+    if (!obj) return [];
+    const data = obj.data || {};
+    const users = Array.isArray(data.users) ? data.users : [];
+    const out = [];
+    for (let i = 0; i < Math.min(limit, users.length); i++) {
+      const u = users[i];
+      if (!u) continue;
+      const followUid = typeof u.id === "number" ? u.id : 0;
+      if (followUid === 0) continue;
+      out.push({
+        uid: followUid,
+        screenName: u.screen_name || "(unnamed)",
+        description: u.description || null,
+        avatarUrl: u.profile_image_url || null,
+        // m.weibo.cn /api/friendships/friends doesn't return follow_time —
+        // 0 lets the snapshot builder fall back to snapshottedAt.
+        followedAt: 0,
+      });
+    }
+    return out;
+  }
+}
+
+module.exports = {
+  WeiboApiClient,
+  // Exposed for tests
+  _internals: {
+    parseWeiboTime,
+    stripHtml,
+    BROWSER_UA,
+    BROWSER_HEADERS,
+  },
+};

package/lib/adapters/social-weibo-adb/collector.js

@@ -0,0 +1,169 @@
+"use strict";
+
+/**
+ * Phase 3a (Weibo C 路径 — 2026-05-25): end-to-end orchestrator.
+ *
+ *   bridge.invoke("weibo.cookies")          ← Phase 3a cookies extension
+ *           │
+ *           ▼  {cookie, diagnostic}
+ *   WeiboApiClient.fetchUid                  ← /api/config 拿 UID + 验登录
+ *           │
+ *           ▼  uid (numeric)
+ *   fetchPosts + fetchFavourites + fetchFollows   (partial-failure OK)
+ *           │
+ *           ▼  3 arrays
+ *   buildSnapshot + writeSnapshotJson        ← schemaVersion=1
+ *           │
+ *           ▼
+ *   registry.syncAdapter("social-weibo", { inputPath })
+ *
+ * Mirror of social-bilibili-adb/collector.js — same `{ok, report?, reason?,
+ * message?}` shape, same try/finally cleanup. **Key diff**: Weibo needs
+ * an extra fetchUid roundtrip after cookies extraction (cookie alone
+ * doesn't carry UID — Bilibili has DedeUserID inline).
+ */
+
+const { WeiboApiClient } = require("./api-client");
+const {
+  buildSnapshot,
+  writeSnapshotJson,
+  cleanupSnapshotJson,
+} = require("./snapshot-builder");
+
+/**
+ * Pull cookies → fetchUid → 3 endpoints → write snapshot. Returns the
+ * staging path + counts + diagnostic.
+ *
+ * Throws (with typed-reason BILIBILI_-style prefix) on cookie failures.
+ * Returns with empty events on /api/config failure or any endpoint
+ * failure (partial-result tolerated — lastErrorCode surfaces the cause
+ * for UI).
+ */
+async function collect(bridge, opts = {}) {
+  if (!bridge || typeof bridge.invoke !== "function") {
+    throw new TypeError(
+      "WeiboAdbCollector.collect: bridge must expose invoke(method, params)",
+    );
+  }
+  const now = opts.now || Date.now;
+  const client = opts.apiClient || new WeiboApiClient();
+  const limits = opts.limits || {};
+
+  // 1. Pull cookies via Phase 3a extension.
+  const cookieResult = await bridge.invoke("weibo.cookies");
+  if (!cookieResult || typeof cookieResult.cookie !== "string") {
+    throw new Error(
+      "WeiboAdbCollector.collect: bridge.invoke('weibo.cookies') returned malformed payload — got cookie=" +
+        typeof cookieResult?.cookie,
+    );
+  }
+  const { cookie, diagnostic: cookieDiagnostic } = cookieResult;
+
+  // 2. fetchUid — required first call. Weibo cookie has no inline UID.
+  const uid = await client.fetchUid(cookie);
+  if (!uid) {
+    // /api/config returned login=false or non-2xx. Could be:
+    //  - cookie expired (most common — user logged out on phone)
+    //  - anti-bot 30x to login HTML (UA missing — but we set browser UA)
+    //  - IO error
+    // Surface as ExtractFailed via the hub-level wrapper; here we
+    // produce an empty-event snapshot so the registry call doesn't
+    // throw (consumers can read douyin.lastErrorCode to disambiguate).
+    const snapshot = buildSnapshot({
+      uid: 1, // sentinel — buildSnapshot requires positive; sync emits 0 events
+      displayName: opts.displayName,
+      snapshottedAt: now(),
+    });
+    const snapshotPath = writeSnapshotJson(snapshot, { dir: opts.stagingDir });
+    return {
+      snapshotPath,
+      uid: null,
+      eventCounts: { post: 0, favourite: 0, follow: 0, total: 0 },
+      lastErrorCode: client.lastErrorCode,
+      lastErrorMessage: client.lastErrorMessage,
+      cookieDiagnostic: cookieDiagnostic || null,
+      uidFetchFailed: true,
+    };
+  }
+
+  // 3. Parallel fetch — partial failure tolerated (client returns []).
+  const [posts, favourites, follows] = await Promise.all([
+    client.fetchPosts(cookie, uid, {
+      limit: Number.isInteger(limits.post) ? limits.post : undefined,
+    }),
+    client.fetchFavourites(cookie, {
+      limit: Number.isInteger(limits.favourite) ? limits.favourite : undefined,
+    }),
+    client.fetchFollows(cookie, uid, {
+      limit: Number.isInteger(limits.follow) ? limits.follow : undefined,
+    }),
+  ]);
+
+  // 4. Build snapshot + write.
+  const snapshot = buildSnapshot({
+    uid,
+    displayName: opts.displayName,
+    posts,
+    favourites,
+    follows,
+    snapshottedAt: now(),
+  });
+  const snapshotPath = writeSnapshotJson(snapshot, { dir: opts.stagingDir });
+
+  return {
+    snapshotPath,
+    uid,
+    eventCounts: {
+      post: posts.length,
+      favourite: favourites.length,
+      follow: follows.length,
+      total: snapshot.events.length,
+    },
+    lastErrorCode: client.lastErrorCode,
+    lastErrorMessage: client.lastErrorMessage,
+    cookieDiagnostic: cookieDiagnostic || null,
+    uidFetchFailed: false,
+  };
+}
+
+/**
+ * Convenience: collect + registry.syncAdapter("social-weibo") + cleanup.
+ */
+async function collectAndSync(bridge, registry, opts = {}) {
+  if (!registry || typeof registry.syncAdapter !== "function") {
+    throw new TypeError(
+      "WeiboAdbCollector.collectAndSync: registry must expose syncAdapter(name, options)",
+    );
+  }
+  const collectResult = await collect(bridge, opts);
+  let syncReport = null;
+  let cleanupFailed = false;
+  try {
+    syncReport = await registry.syncAdapter("social-weibo", {
+      inputPath: collectResult.snapshotPath,
+    });
+  } finally {
+    try {
+      cleanupSnapshotJson(collectResult.snapshotPath);
+    } catch (_e) {
+      cleanupFailed = true;
+    }
+  }
+  return {
+    ...syncReport,
+    weibo: {
+      uid: collectResult.uid,
+      eventCounts: collectResult.eventCounts,
+      lastErrorCode: collectResult.lastErrorCode,
+      lastErrorMessage: collectResult.lastErrorMessage,
+      cookieDiagnostic: collectResult.cookieDiagnostic,
+      uidFetchFailed: collectResult.uidFetchFailed,
+      cleanupFailed,
+    },
+  };
+}
+
+module.exports = {
+  collect,
+  collectAndSync,
+};

package/lib/adapters/social-weibo-adb/cookies-extension.js

@@ -0,0 +1,251 @@
+"use strict";
+
+/**
+ * Phase 3a (Weibo C 路径 — 2026-05-25): weibo.cookies ADB extension factory.
+ *
+ * Mirror of `social-bilibili-adb/cookies-extension.js` (P1a). Pipeline:
+ *
+ *   1. ADB-pull /data/data/com.sina.weibo/app_webview/Default/Cookies
+ *      via `su -c "base64 ..."` streaming (avoids MIUI FUSE SELinux trap)
+ *   2. Parse the chromium-shape sqlite via the shared
+ *      chromium-cookies-reader (Phase 1a generic module)
+ *   3. Filter to host_key match `m.weibo.cn` (Weibo's actual API host;
+ *      `weibo.com` chromium cookies exist on desktop but not on the
+ *      mobile App where chromium-cookies lives)
+ *   4. Validate at minimum SUB cookie present (the session cookie —
+ *      without it /api/config returns "not logged in")
+ *   5. Assemble Cookie header from all m.weibo.cn cookies (Weibo's API
+ *      doesn't enforce a strict required-cookie list like Bilibili's
+ *      5-cookie requirement; pass everything through and let the server
+ *      pick what it needs)
+ *
+ * Returns:
+ *   {
+ *     cookie: string,             // full Cookie header
+ *     extractedAt: number,
+ *     diagnostic: {
+ *       cookieCount: number,
+ *       hadEncrypted: boolean,
+ *       hasSub: boolean,
+ *       cookieNames: string[],
+ *     }
+ *   }
+ *
+ * Failure modes (all throw, UI maps the typed reason to a banner):
+ *   - WEIBO_NOT_INSTALLED — package not on device
+ *   - WEIBO_NO_ROOT — su not available
+ *   - WEIBO_COOKIES_EMPTY — base64 stream returned 0 bytes
+ *   - WEIBO_COOKIES_TRUNCATED — decoded file too small
+ *   - WEIBO_NOT_SQLITE — magic header check failed
+ *   - WEIBO_COOKIES_INCOMPLETE — SUB cookie missing (user logged out
+ *     on the Weibo App or app uses a non-standard storage path)
+ */
+
+const fs = require("node:fs");
+const path = require("node:path");
+const os = require("node:os");
+const crypto = require("node:crypto");
+
+const {
+  readChromiumCookies,
+} = require("../social-bilibili-adb/chromium-cookies-reader");
+
+const WEIBO_COOKIES_REMOTE_PATH =
+  "/data/data/com.sina.weibo/app_webview/Default/Cookies";
+
+const WEIBO_COOKIE_HOST_DOMAIN = "m.weibo.cn";
+
+/** Minimum required cookie name — without SUB, /api/config returns login=false. */
+const WEIBO_REQUIRED_COOKIE = "SUB";
+
+async function pullCookiesViaSu(adb, serial, opts) {
+  const adbOpts = { serial, timeoutMs: opts?.timeoutMs || 60_000 };
+  const lsOut = await adb(
+    [
+      "shell",
+      "su",
+      "-c",
+      `ls ${WEIBO_COOKIES_REMOTE_PATH} 2>/dev/null || echo NOT_FOUND`,
+    ],
+    adbOpts,
+  );
+  const lsLine = lsOut.replace(/\r+$/gm, "").trim();
+  if (lsLine === "NOT_FOUND" || lsLine === "") {
+    throw new Error(
+      "WEIBO_NOT_INSTALLED: " +
+        WEIBO_COOKIES_REMOTE_PATH +
+        " not found. Install Weibo App + log in once on the phone, then retry. (Some Weibo App versions store cookies in a non-default WebView profile dir; if Weibo is installed but the path is missing, file a bug to track the actual path.)",
+    );
+  }
+  // Probe root.
+  const idOut = await adb(["shell", "su", "-c", "id -u"], adbOpts);
+  const idLine = idOut.replace(/\r+$/gm, "").trim();
+  if (idLine !== "0" && !idLine.includes("uid=0")) {
+    throw new Error(
+      "WEIBO_NO_ROOT: this phone isn't rooted (su returned `" +
+        idLine.substring(0, 60) +
+        "`). Weibo release APK isn't debuggable, so root is required to read its Cookies DB.",
+    );
+  }
+  // Stream base64 (avoids MIUI FUSE label remap trap).
+  const b64 = await adb(
+    [
+      "shell",
+      "su",
+      "-c",
+      `base64 ${WEIBO_COOKIES_REMOTE_PATH} | tr -d '\\n\\r'`,
+    ],
+    { ...adbOpts, timeoutMs: opts?.timeoutMs || 60_000 },
+  );
+  const b64Clean = b64.replace(/[\r\n\t ]+/g, "");
+  if (b64Clean.length === 0) {
+    throw new Error(
+      "WEIBO_COOKIES_EMPTY: base64 stream returned 0 bytes (su exec may have silently failed on MIUI / OEM ROM, retry or check `adb logcat`)",
+    );
+  }
+  let buf;
+  try {
+    buf = Buffer.from(b64Clean, "base64");
+  } catch (e) {
+    throw new Error(
+      "WEIBO_BASE64_PARSE: stream wasn't valid base64 (" +
+        (e.message || String(e)) +
+        ")",
+    );
+  }
+  if (buf.length < 1024) {
+    throw new Error(
+      "WEIBO_COOKIES_TRUNCATED: decoded file is only " +
+        buf.length +
+        " bytes — expected ≥4KB sqlite. Possible MIUI silent su fail; check `adb logcat`.",
+    );
+  }
+  const magic = buf.subarray(0, 16).toString("latin1");
+  if (!magic.startsWith("SQLite format 3")) {
+    throw new Error(
+      "WEIBO_NOT_SQLITE: decoded file lacks `SQLite format 3` magic header. Got bytes: " +
+        buf.subarray(0, 16).toString("hex"),
+    );
+  }
+  const tmpDir = os.tmpdir();
+  const tmpFile = path.join(
+    tmpDir,
+    `cc-weibo-cookies-${crypto.randomUUID()}.db`,
+  );
+  fs.writeFileSync(tmpFile, buf);
+  return tmpFile;
+}
+
+/**
+ * Build a Cookie header from the chromium-cookies array. Weibo doesn't
+ * have a strict required-cookie list like Bilibili's 5 — but SUB must
+ * be present (it's the session cookie). Everything else is best-effort
+ * passthrough.
+ */
+function assembleWeiboCookieHeader(cookies) {
+  if (!Array.isArray(cookies)) {
+    throw new TypeError("assembleWeiboCookieHeader: cookies must be an array");
+  }
+  const byName = new Map();
+  for (const c of cookies) {
+    // Most-recently-set wins on duplicate names; prefer more-specific host
+    if (
+      !byName.has(c.name) ||
+      c.hostKey.length > (byName.get(c.name).hostKey || "").length
+    ) {
+      byName.set(c.name, c);
+    }
+  }
+  const hasSub = byName.has(WEIBO_REQUIRED_COOKIE);
+  if (!hasSub) {
+    return {
+      header: null,
+      present: new Set(byName.keys()),
+      missing: [WEIBO_REQUIRED_COOKIE],
+      hasSub: false,
+    };
+  }
+  // Pass everything through — Weibo's m.weibo.cn API picks what it needs
+  // (SUB / SUBP / _T_WM / MLOGIN / WEIBOCN_FROM / etc.)
+  const header = Array.from(byName.values())
+    .map((c) => `${c.name}=${c.value}`)
+    .join("; ");
+  return {
+    header,
+    present: new Set(byName.keys()),
+    missing: [],
+    hasSub: true,
+  };
+}
+
+/**
+ * Factory: returns the extension handler. Same contract as Bilibili
+ * Phase 1a — stateless, no closure-captured device serial.
+ */
+function createWeiboCookiesExtension(factoryOpts = {}) {
+  const timeoutMs = factoryOpts.timeoutMs || 60_000;
+  const onCleanupFailed = factoryOpts.onCleanupFailed || (() => {});
+
+  return async function weiboCookiesHandler(_params, ctx) {
+    if (
+      !ctx ||
+      typeof ctx.adb !== "function" ||
+      typeof ctx.pickDevice !== "function"
+    ) {
+      throw new TypeError(
+        "weibo.cookies extension: ctx must provide {adb, pickDevice} (got " +
+          typeof ctx +
+          ")",
+      );
+    }
+    const serial = await ctx.pickDevice();
+    let tmpFile = null;
+    try {
+      tmpFile = await pullCookiesViaSu(ctx.adb, serial, { timeoutMs });
+      const cookies = readChromiumCookies(tmpFile, WEIBO_COOKIE_HOST_DOMAIN);
+      const cookieCount = cookies.length;
+      const hadEncrypted = (cookies._skippedEncryptedCount || 0) > 0;
+      const { header, missing, present, hasSub } =
+        assembleWeiboCookieHeader(cookies);
+      if (header === null) {
+        throw new Error(
+          "WEIBO_COOKIES_INCOMPLETE: missing required cookie " +
+            JSON.stringify(missing) +
+            ". User probably logged out, or Weibo App uses a non-default WebView storage path (hadEncrypted=" +
+            hadEncrypted +
+            "). Tell user to relog on phone.",
+        );
+      }
+      return {
+        cookie: header,
+        extractedAt: Date.now(),
+        diagnostic: {
+          cookieCount,
+          hadEncrypted,
+          hasSub,
+          cookieNames: Array.from(present),
+        },
+      };
+    } finally {
+      if (tmpFile) {
+        try {
+          fs.unlinkSync(tmpFile);
+        } catch (_e) {
+          onCleanupFailed(tmpFile);
+        }
+      }
+    }
+  };
+}
+
+module.exports = {
+  createWeiboCookiesExtension,
+  WEIBO_COOKIES_REMOTE_PATH,
+  WEIBO_COOKIE_HOST_DOMAIN,
+  WEIBO_REQUIRED_COOKIE,
+  assembleWeiboCookieHeader,
+  // Exposed for tests
+  _internals: {
+    pullCookiesViaSu,
+  },
+};