@chainlesschain/personal-data-hub 0.1.0 → 0.2.1

package/lib/adapters/ai-chat-history/cookie-capture-spec.js

@@ -0,0 +1,331 @@
+/**
+ * AIChat WebView 鉴权向导 — Vendor Cookie Capture Matrix（Phase 10.3.1）
+ *
+ * 与 `vendors/<name>.js` 的 SPEC 解耦：vendor SPEC 只描述 HTTP 抓数据接口，
+ * 本文件描述 wizard 抓 cookie 时需要的"鉴权"维度信息。两层独立，让 adapter
+ * 永远纯 HTTP 可测（注入 mock HttpClient 即可），而 wizard 可单独迭代而不
+ * 触动 adapter。
+ *
+ * Reference: docs/design/Personal_Data_Hub_Phase_10_3_AIChat_WebView_Wizard.md §3
+ *
+ * 每条 entry 的字段约束 (run validateCookieCaptureSpec to enforce)：
+ *   - vendor                ∈ KNOWN_VENDORS
+ *   - loginUrl              http(s):// 开头，host 必须出现在 cookieDomains 的主域内
+ *   - cookieDomains         ≥ 1 个非空字符串（含 ".<root>" 形式）
+ *   - requiredCookies       ≥ 1 个；wizard 至少识别 1 个就认为登录成功
+ *   - postLoginPathHints    ≥ 1 个 path（如 "/chat" / "/c/"）
+ *   - cookieMaxAgeHintDays  正整数；UI 提前 3 天预警
+ *   - notes                 中文用户提示
+ *
+ * 字段都是反向工程结果，**会变**。Phase 10.4 fixture pin 时把每家真实 cookie
+ * 截屏入 `__fixtures__/aichat-cookies/<vendor>.txt` 锁住一版；bump
+ * `COOKIE_SPEC_VERSION` 后 HealthChecker 会主动标 SPEC_VERSION_MISMATCH。
+ */
+
+"use strict";
+
+const COOKIE_SPEC_VERSION = 1;
+
+const KNOWN_VENDORS = Object.freeze([
+  "deepseek",
+  "kimi",
+  "tongyi",
+  "zhipu",
+  "hunyuan",
+  "qianfan",
+  "coze",
+  "dreamina",
+  "doubao",
+]);
+
+const COOKIE_CAPTURE_SPECS = Object.freeze([
+  {
+    vendor: "deepseek",
+    displayName: "DeepSeek",
+    loginUrl: "https://chat.deepseek.com/",
+    cookieDomains: ["chat.deepseek.com", ".deepseek.com"],
+    requiredCookies: ["userToken"],
+    optionalCookies: ["intercom-session-deepseek", "session"],
+    postLoginPathHints: ["/chat", "/a/"],
+    cookieMaxAgeHintDays: 30,
+    notes: "需手机号 / 邮箱 + 验证码登录；自动检测 userToken cookie 出现",
+  },
+  {
+    vendor: "kimi",
+    displayName: "Kimi",
+    loginUrl: "https://kimi.moonshot.cn/",
+    cookieDomains: ["kimi.moonshot.cn", ".moonshot.cn"],
+    requiredCookies: ["access_token"],
+    optionalCookies: ["refresh_token", "session_id"],
+    postLoginPathHints: ["/chat", "/"],
+    cookieMaxAgeHintDays: 30,
+    notes: "手机号验证码登录；access_token 落 cookie 即视为成功",
+  },
+  {
+    vendor: "tongyi",
+    displayName: "通义千问",
+    loginUrl: "https://tongyi.aliyun.com/",
+    cookieDomains: ["tongyi.aliyun.com", ".aliyun.com"],
+    requiredCookies: ["login_aliyunid"],
+    optionalCookies: ["XSRF-TOKEN", "login_aliyunid_csrf", "tongyi_sso_ticket"],
+    postLoginPathHints: ["/qianwen", "/efm"],
+    cookieMaxAgeHintDays: 7,
+    notes: "阿里云账号 SSO；过期较快（约 7 天）需周期重登",
+  },
+  {
+    vendor: "zhipu",
+    displayName: "智谱清言",
+    loginUrl: "https://chatglm.cn/",
+    cookieDomains: ["chatglm.cn", ".chatglm.cn"],
+    requiredCookies: ["chatglm_token"],
+    optionalCookies: ["cgsessionid", "chatglm_user_id"],
+    postLoginPathHints: ["/main", "/"],
+    cookieMaxAgeHintDays: 30,
+    notes: "手机号 + 验证码；chatglm_token 出现即认证成功",
+  },
+  {
+    vendor: "hunyuan",
+    displayName: "腾讯混元",
+    loginUrl: "https://yuanbao.tencent.com/",
+    cookieDomains: ["yuanbao.tencent.com", ".tencent.com"],
+    requiredCookies: ["hy_token"],
+    optionalCookies: ["hy_user", "uin", "skey"],
+    postLoginPathHints: ["/chat", "/"],
+    cookieMaxAgeHintDays: 14,
+    notes: "QQ / 微信 / 手机号；hy_token 落 cookie 视为已登录",
+  },
+  {
+    vendor: "qianfan",
+    displayName: "百度文心",
+    loginUrl: "https://yiyan.baidu.com/",
+    cookieDomains: ["yiyan.baidu.com", ".baidu.com"],
+    requiredCookies: ["BDUSS"],
+    optionalCookies: ["BAIDUID", "STOKEN", "PTOKEN"],
+    postLoginPathHints: ["/chat", "/"],
+    cookieMaxAgeHintDays: 7,
+    notes: "百度账号；BDUSS 跨域 cookie，可能需在百度首页登录后回来",
+  },
+  {
+    vendor: "coze",
+    displayName: "字节扣子 Coze",
+    loginUrl: "https://www.coze.cn/",
+    cookieDomains: ["www.coze.cn", ".coze.cn"],
+    requiredCookies: ["sessionid"],
+    optionalCookies: ["passport_csrf_token", "s_v_web_id", "uid_tt"],
+    postLoginPathHints: ["/home", "/space"],
+    cookieMaxAgeHintDays: 14,
+    notes: "字节统一 passport；sessionid 是 bytedance 通用",
+  },
+  {
+    vendor: "dreamina",
+    displayName: "即梦 Dreamina",
+    loginUrl: "https://jimeng.jianying.com/",
+    cookieDomains: ["jimeng.jianying.com", ".jianying.com"],
+    requiredCookies: ["sessionid"],
+    optionalCookies: ["passport_csrf_token", "s_v_web_id"],
+    postLoginPathHints: ["/ai-tool", "/"],
+    cookieMaxAgeHintDays: 14,
+    notes: "图像生成；与 Coze 共用 bytedance passport sessionid",
+  },
+  {
+    vendor: "doubao",
+    displayName: "豆包 Doubao",
+    loginUrl: "https://www.doubao.com/chat/",
+    cookieDomains: ["www.doubao.com", ".doubao.com"],
+    requiredCookies: ["sessionid"],
+    optionalCookies: ["sid_guard", "passport_csrf_token", "s_v_web_id"],
+    postLoginPathHints: ["/chat"],
+    cookieMaxAgeHintDays: 14,
+    notes: "字节文本 AI；bytedance 通用 sessionid",
+  },
+]);
+
+const SPEC_BY_VENDOR = Object.freeze(
+  COOKIE_CAPTURE_SPECS.reduce((acc, s) => {
+    acc[s.vendor] = s;
+    return acc;
+  }, Object.create(null)),
+);
+
+function getSpec(vendor) {
+  if (!vendor || typeof vendor !== "string") return null;
+  return SPEC_BY_VENDOR[vendor] || null;
+}
+
+function listVendors() {
+  return KNOWN_VENDORS.slice();
+}
+
+/**
+ * Given a probed cookie jar (`{ name: value }` shape), classify which
+ * required cookies are present, which are missing, which optional were
+ * also captured. Returns:
+ *
+ *   { ok, foundRequired, missingRequired, foundOptional }
+ *
+ * `ok === true` iff every required cookie has a non-empty value.
+ *
+ * `cookies` is tolerated as either a plain object, a Cookie[] (Electron
+ * shape), or a raw "k=v; k=v" string (web-shell paste fallback).
+ */
+function classifyProbedCookies(vendor, cookies) {
+  const spec = getSpec(vendor);
+  if (!spec) {
+    return { ok: false, foundRequired: [], missingRequired: [], foundOptional: [], reason: "UNKNOWN_VENDOR" };
+  }
+
+  const jar = _normalizeCookieJar(cookies);
+
+  const foundRequired = [];
+  const missingRequired = [];
+  for (const name of spec.requiredCookies) {
+    const v = jar[name];
+    if (typeof v === "string" && v.length > 0) {
+      foundRequired.push(name);
+    } else {
+      missingRequired.push(name);
+    }
+  }
+
+  const foundOptional = [];
+  for (const name of spec.optionalCookies || []) {
+    const v = jar[name];
+    if (typeof v === "string" && v.length > 0) foundOptional.push(name);
+  }
+
+  return {
+    ok: missingRequired.length === 0 && foundRequired.length > 0,
+    foundRequired,
+    missingRequired,
+    foundOptional,
+  };
+}
+
+function _normalizeCookieJar(input) {
+  if (!input) return {};
+  // Already a plain object { name: value }
+  if (typeof input === "object" && !Array.isArray(input)) {
+    const out = {};
+    for (const [k, v] of Object.entries(input)) {
+      if (typeof v === "string") out[k] = v;
+    }
+    return out;
+  }
+  // Electron `Cookie[]` shape (Cookie has { name, value, ... }).
+  if (Array.isArray(input)) {
+    const out = {};
+    for (const c of input) {
+      if (c && typeof c.name === "string" && typeof c.value === "string") {
+        out[c.name] = c.value;
+      }
+    }
+    return out;
+  }
+  // Raw "k=v; k=v" string (web-shell paste). Tolerates `;`, `; ` and stray
+  // whitespace; only takes the first `=` so values with `=` survive.
+  if (typeof input === "string") {
+    const out = {};
+    for (const pairRaw of input.split(/;\s*/)) {
+      const pair = pairRaw.trim();
+      if (!pair) continue;
+      const idx = pair.indexOf("=");
+      if (idx <= 0) continue;
+      const k = pair.slice(0, idx).trim();
+      const v = pair.slice(idx + 1).trim();
+      if (k && v) out[k] = v;
+    }
+    return out;
+  }
+  return {};
+}
+
+/**
+ * Validate the entire COOKIE_CAPTURE_SPECS array — used both at module
+ * load time (defensive) and by the spec test. Throws on the first
+ * violation with a vendor-prefixed error so spec mistakes surface fast.
+ *
+ * Caller can pass `{ throwOnError: false }` to get `{ ok, errors[] }` for
+ * defensive validation paths.
+ */
+function validateCookieCaptureSpec(specs = COOKIE_CAPTURE_SPECS, opts = {}) {
+  const errors = [];
+  const seen = new Set();
+
+  for (const s of specs) {
+    const where = `vendor=${s && s.vendor}`;
+    if (!s || typeof s !== "object") {
+      errors.push(`${where}: not an object`);
+      continue;
+    }
+    if (!KNOWN_VENDORS.includes(s.vendor)) {
+      errors.push(`${where}: unknown vendor (not in KNOWN_VENDORS)`);
+    }
+    if (seen.has(s.vendor)) {
+      errors.push(`${where}: duplicate vendor entry`);
+    }
+    seen.add(s.vendor);
+
+    if (typeof s.displayName !== "string" || !s.displayName) {
+      errors.push(`${where}: displayName required`);
+    }
+    if (typeof s.loginUrl !== "string" || !/^https?:\/\//.test(s.loginUrl)) {
+      errors.push(`${where}: loginUrl must start with http:// or https://`);
+    } else {
+      try {
+        const u = new URL(s.loginUrl);
+        const host = u.host;
+        const matched = (s.cookieDomains || []).some((d) => {
+          if (typeof d !== "string") return false;
+          if (d.startsWith(".")) return host.endsWith(d.slice(1));
+          return host === d;
+        });
+        if (!matched) {
+          errors.push(
+            `${where}: loginUrl host "${host}" does not match any cookieDomain entry`,
+          );
+        }
+      } catch (urlErr) {
+        errors.push(`${where}: loginUrl unparseable (${urlErr.message})`);
+      }
+    }
+    if (!Array.isArray(s.cookieDomains) || s.cookieDomains.length < 1) {
+      errors.push(`${where}: cookieDomains must be a non-empty array`);
+    }
+    if (!Array.isArray(s.requiredCookies) || s.requiredCookies.length < 1) {
+      errors.push(`${where}: requiredCookies must be a non-empty array`);
+    }
+    if (s.optionalCookies && !Array.isArray(s.optionalCookies)) {
+      errors.push(`${where}: optionalCookies must be an array if present`);
+    }
+    if (!Array.isArray(s.postLoginPathHints) || s.postLoginPathHints.length < 1) {
+      errors.push(`${where}: postLoginPathHints must be a non-empty array`);
+    }
+    if (!Number.isInteger(s.cookieMaxAgeHintDays) || s.cookieMaxAgeHintDays <= 0) {
+      errors.push(`${where}: cookieMaxAgeHintDays must be a positive integer`);
+    }
+    if (typeof s.notes !== "string" || !s.notes) {
+      errors.push(`${where}: notes required`);
+    }
+  }
+
+  if (errors.length > 0 && opts.throwOnError !== false) {
+    throw new Error("Invalid cookie capture spec: " + errors.join("; "));
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+// Defensive load-time check — if specs ship malformed in a future patch,
+// the module fails fast at require() rather than at first wizard call.
+validateCookieCaptureSpec();
+
+module.exports = {
+  COOKIE_SPEC_VERSION,
+  KNOWN_VENDORS,
+  COOKIE_CAPTURE_SPECS,
+  getSpec,
+  listVendors,
+  classifyProbedCookies,
+  validateCookieCaptureSpec,
+  // exported for tests
+  _internal: { _normalizeCookieJar },
+};

package/lib/adapters/ai-chat-history/health-checker.js

@@ -0,0 +1,210 @@
+/**
+ * AIChat WebView 鉴权向导 — HealthChecker (Phase 10.3.5).
+ *
+ * Periodic worker that walks every registered AIChat vendor and re-runs
+ * `vendorAdapter.registerVendor(vendor, cookies)` against the *current*
+ * cookies in `aichat-accounts.json`. Result writes back to the entry as:
+ *
+ *   entry.lastHealth = { ok, reason?, at }
+ *
+ * The wizard UI (Step 1 card grid) reads `lastHealth.ok` to render the red
+ * dot / "Cookie 即将过期" / "🔴 重登" affordance.
+ *
+ * Wiring:
+ *   const hc = createAIChatHealthChecker({
+ *     accountsStore,
+ *     vendorAdapter,            // same bridge used by Wizard (registerVendor)
+ *     intervalMs: 6 * 3600_000, // default 6h
+ *     firstRunDelayMs: 30_000,  // first check 30s after start
+ *     specVersion: 1,           // bump on incompatible spec changes
+ *   });
+ *   hc.start();
+ *   …
+ *   hc.stop();
+ *
+ * Test seam: pass `_deps.setInterval` / `_deps.clearInterval` /
+ * `_deps.setTimeout` / `_deps.clock` so vitest can fast-forward without
+ * needing fake timers + real timers in the same suite.
+ *
+ * Reference: docs/design/Personal_Data_Hub_Phase_10_3_AIChat_WebView_Wizard.md §6
+ */
+
+"use strict";
+
+const DEFAULT_INTERVAL_MS = 6 * 60 * 60 * 1000; // 6h
+const DEFAULT_FIRST_RUN_DELAY_MS = 30_000; // 30s after start
+
+function createAIChatHealthChecker({
+  accountsStore,
+  vendorAdapter,
+  intervalMs = DEFAULT_INTERVAL_MS,
+  firstRunDelayMs = DEFAULT_FIRST_RUN_DELAY_MS,
+  specVersion = 1,
+  _deps,
+} = {}) {
+  if (!accountsStore || typeof accountsStore.list !== "function") {
+    throw new Error("aichat-health-checker: accountsStore.list required");
+  }
+  if (typeof accountsStore.put !== "function") {
+    throw new Error("aichat-health-checker: accountsStore.put required");
+  }
+  if (!vendorAdapter || typeof vendorAdapter.registerVendor !== "function") {
+    throw new Error("aichat-health-checker: vendorAdapter.registerVendor required");
+  }
+
+  const defaults = {
+    setInterval: (fn, ms) => globalThis.setInterval(fn, ms),
+    clearInterval: (h) => globalThis.clearInterval(h),
+    setTimeout: (fn, ms) => globalThis.setTimeout(fn, ms),
+    clearTimeout: (h) => globalThis.clearTimeout(h),
+    clock: () => Date.now(),
+    logger: { info: () => {}, warn: () => {}, error: () => {} },
+  };
+  // Merge instead of replace so tests can supply just the timer slots and
+  // inherit a no-op logger / Date.now clock from defaults.
+  const deps = { ...defaults, ..._deps };
+
+  let intervalHandle = null;
+  let firstRunHandle = null;
+  let running = false;
+  let lastRunAt = 0;
+  let _runs = 0;
+
+  /**
+   * Walk all registered vendors, refresh their lastHealth.
+   *
+   * - If `cookieSpecVersion` < current `specVersion` → mark SPEC_VERSION_MISMATCH
+   * - Else call vendorAdapter.registerVendor with the stored cookies and
+   *   propagate the result. The bridge already maps to validateCookie under
+   *   the hood (matches the registerVendor contract from the wizard).
+   *
+   * Returns `{ checked, ok, failed, mismatch }` for callers / tests.
+   */
+  async function runOnce() {
+    if (running) {
+      deps.logger.warn("[aichat-health] previous run still in flight, skipping");
+      return { checked: 0, ok: 0, failed: 0, mismatch: 0, skipped: true };
+    }
+    running = true;
+    const start = deps.clock();
+    let checked = 0;
+    let ok = 0;
+    let failed = 0;
+    let mismatch = 0;
+    try {
+      const entries = (await accountsStore.list()) || [];
+      for (const entry of entries) {
+        if (!entry || !entry.vendor) continue;
+        checked++;
+        // Spec version downgrade trap (T7) — the on-disk cookies were
+        // captured under an older cookie-capture-spec version; cookies may
+        // still work but mark them so the UI flags re-login.
+        const entryVer = Number.isFinite(entry.cookieSpecVersion) ? entry.cookieSpecVersion : 0;
+        if (entryVer < specVersion) {
+          mismatch++;
+          await _writeHealth(entry, {
+            ok: false,
+            reason: "SPEC_VERSION_MISMATCH",
+            at: deps.clock(),
+          });
+          continue;
+        }
+        let result;
+        try {
+          result = await vendorAdapter.registerVendor(entry.vendor, entry.cookies || {});
+        } catch (err) {
+          deps.logger.warn(
+            `[aichat-health] ${entry.vendor} registerVendor threw`,
+            err && err.message,
+          );
+          result = { ok: false, reason: "ADAPTER_THREW", error: err && err.message };
+        }
+        if (result && result.ok === true) {
+          ok++;
+          await _writeHealth(entry, { ok: true, at: deps.clock() });
+        } else {
+          failed++;
+          await _writeHealth(entry, {
+            ok: false,
+            reason: (result && result.reason) || "VALIDATE_FAILED",
+            at: deps.clock(),
+          });
+        }
+      }
+      lastRunAt = start;
+      _runs++;
+      deps.logger.info(
+        `[aichat-health] checked=${checked} ok=${ok} failed=${failed} mismatch=${mismatch}`,
+      );
+      return { checked, ok, failed, mismatch };
+    } finally {
+      running = false;
+    }
+  }
+
+  async function _writeHealth(entry, lastHealth) {
+    const next = { ...entry, lastHealth };
+    try {
+      await accountsStore.put(entry.vendor, next);
+    } catch (err) {
+      deps.logger.warn(`[aichat-health] write back ${entry.vendor} failed`, err && err.message);
+    }
+  }
+
+  /**
+   * Begin the periodic loop. Idempotent — second call returns early.
+   * Schedules:
+   *   - first run firstRunDelayMs after start()
+   *   - subsequent runs every intervalMs
+   */
+  function start() {
+    if (intervalHandle || firstRunHandle) {
+      return false;
+    }
+    firstRunHandle = deps.setTimeout(() => {
+      firstRunHandle = null;
+      // Fire-and-forget; runOnce is internally guarded.
+      runOnce().catch((err) =>
+        deps.logger.error("[aichat-health] first run failed", err && err.message),
+      );
+      intervalHandle = deps.setInterval(() => {
+        runOnce().catch((err) =>
+          deps.logger.error("[aichat-health] interval run failed", err && err.message),
+        );
+      }, intervalMs);
+    }, firstRunDelayMs);
+    return true;
+  }
+
+  function stop() {
+    if (firstRunHandle) {
+      deps.clearTimeout(firstRunHandle);
+      firstRunHandle = null;
+    }
+    if (intervalHandle) {
+      deps.clearInterval(intervalHandle);
+      intervalHandle = null;
+    }
+    return true;
+  }
+
+  function status() {
+    return {
+      running,
+      started: !!(firstRunHandle || intervalHandle),
+      lastRunAt,
+      runs: _runs,
+      intervalMs,
+      firstRunDelayMs,
+      specVersion,
+    };
+  }
+
+  return { start, stop, runOnce, status };
+}
+
+module.exports = {
+  createAIChatHealthChecker,
+  DEFAULT_INTERVAL_MS,
+  DEFAULT_FIRST_RUN_DELAY_MS,
+};