mslxdff 0.1.203 → 0.1.208

package/src/providers/raccoon/account-store.js

@@ -1,216 +1,216 @@
-// raccoon 账号落盘单一源：auths/raccoon-<uid>.json（0600 tmp+rename）+ state.json providerConfigs.raccoon.keys 同步。
-// office_identity 与 device_id（per-account 持久 UUID）随账号文档走，**不进 providerConfigs**——
-// 规避 providerConfig 重建路径（allowlist/baseUrl 写回）静默丢字段的既有故障类（与 zcode 同款理由）。
-import { writeFileSync, mkdirSync, existsSync, renameSync, unlinkSync, readdirSync, readFileSync, chmodSync } from "node:fs";
-import { join, dirname } from "node:path";
-import { tmpdir } from "node:os";
-import { uuid } from "../../compat.js";
-import { isTestEnv, defaultStateFile } from "../../state/store.js";
-
-export function raccoonAuthDir({ explicit = "", testEnv = false, stateFile } = {}) {
-  if (explicit) return explicit;
-  if (testEnv) return join(tmpdir(), "mslxdff-test-auths");
-  return join(dirname(stateFile), "auths");
-}
-
-export function resolveRaccoonAuthDir() {
-  return raccoonAuthDir({
-    explicit: process.env.MSLXDFF_RACCOON_AUTH_DIR || "",
-    testEnv: isTestEnv(),
-    stateFile: defaultStateFile(),
-  });
-}
-
-/** 主目录 + 历史遗留 cwd/auths（只读兜底，防旧副本「复活」）。 */
-export function resolveRaccoonAuthDirs() {
-  const primary = resolveRaccoonAuthDir();
-  const cwdDir = join(process.cwd(), "auths");
-  return primary === cwdDir ? [primary] : [primary, cwdDir];
-}
-
-/** 列出全部落盘账号（同 uid 主位置优先），跳过无 access_token 的残档。 */
-export function listRaccoonAccountDocs({ dirs } = {}) {
-  const out = [];
-  const seen = new Set();
-  for (const dir of dirs || resolveRaccoonAuthDirs()) {
-    let files = [];
-    try {
-      if (!existsSync(dir)) continue;
-      files = readdirSync(dir).filter((f) => f.startsWith("raccoon-") && f.endsWith(".json"));
-    } catch {
-      continue;
-    }
-    for (const f of files) {
-      try {
-        const doc = JSON.parse(readFileSync(join(dir, f), "utf8"));
-        const uid = doc?.account?.uid;
-        const token = doc?.auth?.access_token;
-        if (!uid || !token) continue;
-        if (seen.has(String(uid))) continue;
-        seen.add(String(uid));
-        out.push({
-          uid: String(uid),
-          accessToken: String(token),
-          refreshToken: String(doc.auth.refresh_token || ""),
-          expiresAt: String(doc.auth.expires_at || ""),
-          officeIdentity: String(doc.auth.office_identity || ""),
-          deviceId: String(doc.auth.device_id || ""),
-          name: String(doc.account.name || ""),
-          phone: String(doc.account.phone || ""),
-          file: join(dir, f),
-          dir,
-          doc,
-        });
-      } catch {}
-    }
-  }
-  return out;
-}
-
-function accountFilePath(uid, dir) {
-  return join(dir, `raccoon-${uid}.json`);
-}
-
-export function writeRaccoonAccountFile(
-  { uid, accessToken, refreshToken = "", expiresAt = "", officeIdentity = "", deviceId = "", name = "", phone = "" },
-  { dir = resolveRaccoonAuthDir() } = {},
-) {
-  mkdirSync(dir, { recursive: true });
-  const doc = {
-    account: { uid, name, phone },
-    auth: {
-      access_token: accessToken,
-      refresh_token: refreshToken,
-      expires_at: expiresAt,
-      office_identity: officeIdentity,
-      device_id: deviceId,
-    },
-  };
-  const fp = accountFilePath(uid, dir);
-  const tmp = `${fp}.${process.pid}.${Math.random().toString(36).slice(2, 10)}.tmp`; // 唯一名：防并发写（daemon 续期 vs CLI login）互相踩
-  writeFileSync(tmp, JSON.stringify(doc, null, 2), { mode: 0o600 });
-  try {
-    if (existsSync(fp)) {
-      try { chmodSync(fp, 0o600); } catch {}
-      unlinkSync(fp);
-    }
-    renameSync(tmp, fp);
-  } catch {
-    // 兜底也走「唯一 tmp + rename」，绝不直写正式文件（直写非原子，并发读者会读到半截 JSON → 该号静默消失）
-    try { const t2 = `${fp}.${process.pid}.${Math.random().toString(36).slice(2, 10)}.tmp`; writeFileSync(t2, JSON.stringify(doc, null, 2), { mode: 0o600 }); if (existsSync(fp)) unlinkSync(fp); renameSync(t2, fp); } catch {}
-    try { unlinkSync(tmp); } catch {}
-  }
-  try { chmodSync(fp, 0o600); } catch {} // mode 只在新建成时生效，存量必须补 chmod
-  return fp;
-}
-
-export function readRaccoonAccountDoc(uid, { dir = resolveRaccoonAuthDir() } = {}) {
-  try {
-    return JSON.parse(readFileSync(accountFilePath(uid, dir), "utf8"));
-  } catch {
-    return null;
-  }
-}
-
-/** 落盘账号文档并同步 state 的 keys；已有 device_id 时复用，不覆盖。 */
-export async function saveRaccoonAccount({
-  uid,
-  accessToken,
-  refreshToken = "",
-  expiresAt = "",
-  officeIdentity = "",
-  deviceId = "",
-  name = "",
-  phone = "",
-  dir,
-  file,
-} = {}) {
-  if (!uid || !accessToken) throw new Error("saveRaccoonAccount: 缺少 uid/accessToken");
-  const targetDir = dir || resolveRaccoonAuthDir();
-  const existing = readRaccoonAccountDoc(uid, { dir: targetDir });
-  const device = deviceId || existing?.auth?.device_id || uuid();
-  const fp = writeRaccoonAccountFile(
-    { uid, accessToken, refreshToken, expiresAt, officeIdentity, deviceId: device, name, phone },
-    { dir: targetDir },
-  );
-
-  // keys 一律以账号文档为准（覆盖式，见 syncRaccoonKeys 的说明）
-  const sync = await syncRaccoonKeys({ dirs: [targetDir], ...(file ? { file } : {}) });
-  return { file: fp, keys: sync.keys.length, updated: Boolean(existing) };
-}
-
-/** device_id：账号文档内持久复用；缺失且已有 token 时生成并写回。 */
-export function ensureRaccoonDeviceId({ uid, dir } = {}) {
-  if (!uid) return "";
-  const targetDir = dir || resolveRaccoonAuthDir();
-  const doc = readRaccoonAccountDoc(uid, { dir: targetDir });
-  const cur = String(doc?.auth?.device_id || "").trim();
-  if (cur) return cur;
-  const device = uuid();
-  if (doc?.auth?.access_token) {
-    writeRaccoonAccountFile(
-      {
-        uid,
-        accessToken: doc.auth.access_token,
-        refreshToken: doc.auth?.refresh_token || "",
-        expiresAt: doc.auth?.expires_at || "",
-        officeIdentity: doc.auth?.office_identity || "",
-        deviceId: device,
-        name: doc.account?.name || "",
-        phone: doc.account?.phone || "",
-      },
-      { dir: targetDir },
-    );
-  }
-  return device;
-}
-
-/** 续期结果回写（refresh 可能不返回新 refresh_token，不能覆盖成空串）。 */
-export function applyRaccoonRefresh(existing, { accessToken, refreshToken, expiresAt }) {
-  return {
-    ...existing,
-    access_token: accessToken,
-    refresh_token: refreshToken && refreshToken.length > 0 ? refreshToken : existing.refresh_token,
-    expires_at: expiresAt || existing.expires_at || "",
-  };
-}
-
-/**
- * 账号文档 → provider/credits 认的 credential 形状。**单一源**：此前 index.js 的 credentialFor、
- * runtime/raccoon-checkin.js 与 CLI 各自内联一份，漏一个 `expires_at` 就会让过期/临期判定静默失效。
- * 输入是 listRaccoonAccountDocs() 的 camelCase 条目，输出是上游口径的 snake_case credential。
- */
-export function raccoonCredentialFromDoc(doc) {
-  return {
-    access_token: doc?.accessToken || "",
-    refresh_token: doc?.refreshToken || "",
-    expires_at: doc?.expiresAt || "",
-    office_identity: doc?.officeIdentity || "",
-    device_id: doc?.deviceId || "",
-    uid: doc?.uid || "",
-  };
-}
-
-/**
- * providerConfigs.raccoon.keys ← auths/ 各号文档里的当前 access_token（**覆盖式**，不是追加）。
- * 为什么必须覆盖（两个都是踩过的坑）：
- *   1) access_token 约 3 小时一换，追加会让 keys 越攒越多已作废 token，ring 反复选中它们去撞 401；
- *   2) 续期回写只改账号文档（writeRaccoonAccountFile 从不碰 keys），两者一分叉，daemon 重启后拿到的
- *      就是过期 token —— 症状是「明明登录过、积分还在，却恒 401 / 429 全号冷却」，只能重扫码。
- * 账号文档是身份的唯一可信源（refresh_token / office_identity / device_id 只在文档里），
- * 所以 keys 以它为准；不在任何文档里的 token 一律剔除。
- */
-export async function syncRaccoonKeys({ dirs, file } = {}) {
-  const { loadProviderConfig, saveProviderConfig } = await import("../../state.js");
-  const tokens = [...new Set(
-    listRaccoonAccountDocs(dirs ? { dirs } : {})
-      .map((d) => String(d?.accessToken || "").trim())
-      .filter(Boolean),
-  )];
-  const cfg = loadProviderConfig("raccoon", file ? { file } : {}) || {};
-  const prev = Array.isArray(cfg.keys) ? cfg.keys : [];
-  const identical = prev.length === tokens.length && prev.every((k) => tokens.includes(k));
-  if (identical) return { keys: tokens, changed: false, dropped: 0 };
-  saveProviderConfig("raccoon", { ...cfg, keys: tokens }, file ? { file } : {});
-  return { keys: tokens, changed: true, dropped: prev.filter((k) => !tokens.includes(k)).length };
-}
+// raccoon 账号落盘单一源：auths/raccoon-<uid>.json（0600 tmp+rename）+ state.json providerConfigs.raccoon.keys 同步。
+// office_identity 与 device_id（per-account 持久 UUID）随账号文档走，**不进 providerConfigs**——
+// 规避 providerConfig 重建路径（allowlist/baseUrl 写回）静默丢字段的既有故障类（与 zcode 同款理由）。
+import { writeFileSync, mkdirSync, existsSync, renameSync, unlinkSync, readdirSync, readFileSync, chmodSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { tmpdir } from "node:os";
+import { uuid } from "../../compat.js";
+import { isTestEnv, defaultStateFile } from "../../state/store.js";
+
+export function raccoonAuthDir({ explicit = "", testEnv = false, stateFile } = {}) {
+  if (explicit) return explicit;
+  if (testEnv) return join(tmpdir(), "mslxdff-test-auths");
+  return join(dirname(stateFile), "auths");
+}
+
+export function resolveRaccoonAuthDir() {
+  return raccoonAuthDir({
+    explicit: process.env.MSLXDFF_RACCOON_AUTH_DIR || "",
+    testEnv: isTestEnv(),
+    stateFile: defaultStateFile(),
+  });
+}
+
+/** 主目录 + 历史遗留 cwd/auths（只读兜底，防旧副本「复活」）。 */
+export function resolveRaccoonAuthDirs() {
+  const primary = resolveRaccoonAuthDir();
+  const cwdDir = join(process.cwd(), "auths");
+  return primary === cwdDir ? [primary] : [primary, cwdDir];
+}
+
+/** 列出全部落盘账号（同 uid 主位置优先），跳过无 access_token 的残档。 */
+export function listRaccoonAccountDocs({ dirs } = {}) {
+  const out = [];
+  const seen = new Set();
+  for (const dir of dirs || resolveRaccoonAuthDirs()) {
+    let files = [];
+    try {
+      if (!existsSync(dir)) continue;
+      files = readdirSync(dir).filter((f) => f.startsWith("raccoon-") && f.endsWith(".json"));
+    } catch {
+      continue;
+    }
+    for (const f of files) {
+      try {
+        const doc = JSON.parse(readFileSync(join(dir, f), "utf8"));
+        const uid = doc?.account?.uid;
+        const token = doc?.auth?.access_token;
+        if (!uid || !token) continue;
+        if (seen.has(String(uid))) continue;
+        seen.add(String(uid));
+        out.push({
+          uid: String(uid),
+          accessToken: String(token),
+          refreshToken: String(doc.auth.refresh_token || ""),
+          expiresAt: String(doc.auth.expires_at || ""),
+          officeIdentity: String(doc.auth.office_identity || ""),
+          deviceId: String(doc.auth.device_id || ""),
+          name: String(doc.account.name || ""),
+          phone: String(doc.account.phone || ""),
+          file: join(dir, f),
+          dir,
+          doc,
+        });
+      } catch {}
+    }
+  }
+  return out;
+}
+
+function accountFilePath(uid, dir) {
+  return join(dir, `raccoon-${uid}.json`);
+}
+
+export function writeRaccoonAccountFile(
+  { uid, accessToken, refreshToken = "", expiresAt = "", officeIdentity = "", deviceId = "", name = "", phone = "" },
+  { dir = resolveRaccoonAuthDir() } = {},
+) {
+  mkdirSync(dir, { recursive: true });
+  const doc = {
+    account: { uid, name, phone },
+    auth: {
+      access_token: accessToken,
+      refresh_token: refreshToken,
+      expires_at: expiresAt,
+      office_identity: officeIdentity,
+      device_id: deviceId,
+    },
+  };
+  const fp = accountFilePath(uid, dir);
+  const tmp = `${fp}.${process.pid}.${Math.random().toString(36).slice(2, 10)}.tmp`; // 唯一名：防并发写（daemon 续期 vs CLI login）互相踩
+  writeFileSync(tmp, JSON.stringify(doc, null, 2), { mode: 0o600 });
+  try {
+    if (existsSync(fp)) {
+      try { chmodSync(fp, 0o600); } catch {}
+      unlinkSync(fp);
+    }
+    renameSync(tmp, fp);
+  } catch {
+    // 兜底也走「唯一 tmp + rename」，绝不直写正式文件（直写非原子，并发读者会读到半截 JSON → 该号静默消失）
+    try { const t2 = `${fp}.${process.pid}.${Math.random().toString(36).slice(2, 10)}.tmp`; writeFileSync(t2, JSON.stringify(doc, null, 2), { mode: 0o600 }); if (existsSync(fp)) unlinkSync(fp); renameSync(t2, fp); } catch {}
+    try { unlinkSync(tmp); } catch {}
+  }
+  try { chmodSync(fp, 0o600); } catch {} // mode 只在新建成时生效，存量必须补 chmod
+  return fp;
+}
+
+export function readRaccoonAccountDoc(uid, { dir = resolveRaccoonAuthDir() } = {}) {
+  try {
+    return JSON.parse(readFileSync(accountFilePath(uid, dir), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/** 落盘账号文档并同步 state 的 keys；已有 device_id 时复用，不覆盖。 */
+export async function saveRaccoonAccount({
+  uid,
+  accessToken,
+  refreshToken = "",
+  expiresAt = "",
+  officeIdentity = "",
+  deviceId = "",
+  name = "",
+  phone = "",
+  dir,
+  file,
+} = {}) {
+  if (!uid || !accessToken) throw new Error("saveRaccoonAccount: 缺少 uid/accessToken");
+  const targetDir = dir || resolveRaccoonAuthDir();
+  const existing = readRaccoonAccountDoc(uid, { dir: targetDir });
+  const device = deviceId || existing?.auth?.device_id || uuid();
+  const fp = writeRaccoonAccountFile(
+    { uid, accessToken, refreshToken, expiresAt, officeIdentity, deviceId: device, name, phone },
+    { dir: targetDir },
+  );
+
+  // keys 一律以账号文档为准（覆盖式，见 syncRaccoonKeys 的说明）
+  const sync = await syncRaccoonKeys({ dirs: [targetDir], ...(file ? { file } : {}) });
+  return { file: fp, keys: sync.keys.length, updated: Boolean(existing) };
+}
+
+/** device_id：账号文档内持久复用；缺失且已有 token 时生成并写回。 */
+export function ensureRaccoonDeviceId({ uid, dir } = {}) {
+  if (!uid) return "";
+  const targetDir = dir || resolveRaccoonAuthDir();
+  const doc = readRaccoonAccountDoc(uid, { dir: targetDir });
+  const cur = String(doc?.auth?.device_id || "").trim();
+  if (cur) return cur;
+  const device = uuid();
+  if (doc?.auth?.access_token) {
+    writeRaccoonAccountFile(
+      {
+        uid,
+        accessToken: doc.auth.access_token,
+        refreshToken: doc.auth?.refresh_token || "",
+        expiresAt: doc.auth?.expires_at || "",
+        officeIdentity: doc.auth?.office_identity || "",
+        deviceId: device,
+        name: doc.account?.name || "",
+        phone: doc.account?.phone || "",
+      },
+      { dir: targetDir },
+    );
+  }
+  return device;
+}
+
+/** 续期结果回写（refresh 可能不返回新 refresh_token，不能覆盖成空串）。 */
+export function applyRaccoonRefresh(existing, { accessToken, refreshToken, expiresAt }) {
+  return {
+    ...existing,
+    access_token: accessToken,
+    refresh_token: refreshToken && refreshToken.length > 0 ? refreshToken : existing.refresh_token,
+    expires_at: expiresAt || existing.expires_at || "",
+  };
+}
+
+/**
+ * 账号文档 → provider/credits 认的 credential 形状。**单一源**：此前 index.js 的 credentialFor、
+ * runtime/raccoon-checkin.js 与 CLI 各自内联一份，漏一个 `expires_at` 就会让过期/临期判定静默失效。
+ * 输入是 listRaccoonAccountDocs() 的 camelCase 条目，输出是上游口径的 snake_case credential。
+ */
+export function raccoonCredentialFromDoc(doc) {
+  return {
+    access_token: doc?.accessToken || "",
+    refresh_token: doc?.refreshToken || "",
+    expires_at: doc?.expiresAt || "",
+    office_identity: doc?.officeIdentity || "",
+    device_id: doc?.deviceId || "",
+    uid: doc?.uid || "",
+  };
+}
+
+/**
+ * providerConfigs.raccoon.keys ← auths/ 各号文档里的当前 access_token（**覆盖式**，不是追加）。
+ * 为什么必须覆盖（两个都是踩过的坑）：
+ *   1) access_token 约 3 小时一换，追加会让 keys 越攒越多已作废 token，ring 反复选中它们去撞 401；
+ *   2) 续期回写只改账号文档（writeRaccoonAccountFile 从不碰 keys），两者一分叉，daemon 重启后拿到的
+ *      就是过期 token —— 症状是「明明登录过、积分还在，却恒 401 / 429 全号冷却」，只能重扫码。
+ * 账号文档是身份的唯一可信源（refresh_token / office_identity / device_id 只在文档里），
+ * 所以 keys 以它为准；不在任何文档里的 token 一律剔除。
+ */
+export async function syncRaccoonKeys({ dirs, file } = {}) {
+  const { loadProviderConfig, saveProviderConfig } = await import("../../state.js");
+  const tokens = [...new Set(
+    listRaccoonAccountDocs(dirs ? { dirs } : {})
+      .map((d) => String(d?.accessToken || "").trim())
+      .filter(Boolean),
+  )];
+  const cfg = loadProviderConfig("raccoon", file ? { file } : {}) || {};
+  const prev = Array.isArray(cfg.keys) ? cfg.keys : [];
+  const identical = prev.length === tokens.length && prev.every((k) => tokens.includes(k));
+  if (identical) return { keys: tokens, changed: false, dropped: 0 };
+  saveProviderConfig("raccoon", { ...cfg, keys: tokens }, file ? { file } : {});
+  return { keys: tokens, changed: true, dropped: prev.filter((k) => !tokens.includes(k)).length };
+}

package/src/providers/raccoon/auth.js

@@ -1,67 +1,67 @@
-// raccoon 鉴权材料工具：JWT 过期判断、token 指纹、uid 归一。
-// 指纹用于 CLI 脱敏回执与日志——**token 原文绝不出现在输出里**。
-import { createHash } from "node:crypto";
-
-/** 解析 JWT payload 的 `exp`（秒 → 毫秒）；坏格式/缺字段返回 undefined。 */
-export function decodeJwtExpMs(token) {
-  if (typeof token !== "string" || token.length === 0) return undefined;
-  const parts = token.split(".");
-  if (parts.length < 2) return undefined;
-  try {
-    const payload = JSON.parse(Buffer.from(parts[1] ?? "", "base64url").toString("utf8"));
-    if (typeof payload !== "object" || payload === null || Array.isArray(payload)) return undefined;
-    const exp = payload.exp;
-    if (typeof exp !== "number" || !Number.isFinite(exp) || exp <= 0) return undefined;
-    return exp * 1000;
-  } catch {
-    return undefined;
-  }
-}
-
-/**
- * 凭据到期时刻（毫秒）：优先账号文档里的 `expires_at`（字符串，支持秒或毫秒），
- * 缺失时回落 JWT 自身的 `exp`。两者都拿不到 → undefined（视为「不知何时过期」，不主动判过期）。
- */
-export function raccoonCredentialExpiresAtMs(credential) {
-  const raw = credential?.expires_at;
-  if (typeof raw === "string" && raw.trim().length > 0) {
-    const n = Number(raw);
-    if (Number.isFinite(n) && n > 0) return n > 1e12 ? n : n * 1000;
-  }
-  if (typeof raw === "number" && Number.isFinite(raw) && raw > 0) return raw > 1e12 ? raw : raw * 1000;
-  return decodeJwtExpMs(credential?.access_token);
-}
-
-/** 是否已过期（拿不到到期时刻时保守返回 false，交给上游 401 判）。 */
-export function isRaccoonExpired(credential, now = Date.now()) {
-  const exp = raccoonCredentialExpiresAtMs(credential);
-  return exp === undefined ? false : now >= exp;
-}
-
-/** 到期前提前量（默认 60s）：临期即刷新，避免请求正好撞在过期瞬间。 */
-export const RACCOON_REFRESH_SKEW_MS = 60_000;
-
-export function isRaccoonExpiringSoon(credential, now = Date.now(), skewMs = RACCOON_REFRESH_SKEW_MS) {
-  const exp = raccoonCredentialExpiresAtMs(credential);
-  return exp === undefined ? false : now + skewMs >= exp;
-}
-
-/** token 指纹：sha256 前 8 位十六进制。**唯一允许出现在日志/CLI 里的 token 表示**。 */
-export function raccoonTokenFingerprint(token) {
-  const s = String(token || "");
-  if (!s) return "";
-  try {
-    return createHash("sha256").update(s).digest("hex").slice(0, 8);
-  } catch {
-    return "";
-  }
-}
-
-/** uid 归一：优先 user_info 的 id，其次 office/userId，最后回退 token 指纹（保证非空且稳定）。 */
-export function resolveRaccoonUid({ userId = "", officeIdentity = "", token = "" } = {}) {
-  for (const candidate of [userId, officeIdentity]) {
-    const s = String(candidate || "").trim();
-    if (s) return s;
-  }
-  return raccoonTokenFingerprint(token);
-}
+// raccoon 鉴权材料工具：JWT 过期判断、token 指纹、uid 归一。
+// 指纹用于 CLI 脱敏回执与日志——**token 原文绝不出现在输出里**。
+import { createHash } from "node:crypto";
+
+/** 解析 JWT payload 的 `exp`（秒 → 毫秒）；坏格式/缺字段返回 undefined。 */
+export function decodeJwtExpMs(token) {
+  if (typeof token !== "string" || token.length === 0) return undefined;
+  const parts = token.split(".");
+  if (parts.length < 2) return undefined;
+  try {
+    const payload = JSON.parse(Buffer.from(parts[1] ?? "", "base64url").toString("utf8"));
+    if (typeof payload !== "object" || payload === null || Array.isArray(payload)) return undefined;
+    const exp = payload.exp;
+    if (typeof exp !== "number" || !Number.isFinite(exp) || exp <= 0) return undefined;
+    return exp * 1000;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * 凭据到期时刻（毫秒）：优先账号文档里的 `expires_at`（字符串，支持秒或毫秒），
+ * 缺失时回落 JWT 自身的 `exp`。两者都拿不到 → undefined（视为「不知何时过期」，不主动判过期）。
+ */
+export function raccoonCredentialExpiresAtMs(credential) {
+  const raw = credential?.expires_at;
+  if (typeof raw === "string" && raw.trim().length > 0) {
+    const n = Number(raw);
+    if (Number.isFinite(n) && n > 0) return n > 1e12 ? n : n * 1000;
+  }
+  if (typeof raw === "number" && Number.isFinite(raw) && raw > 0) return raw > 1e12 ? raw : raw * 1000;
+  return decodeJwtExpMs(credential?.access_token);
+}
+
+/** 是否已过期（拿不到到期时刻时保守返回 false，交给上游 401 判）。 */
+export function isRaccoonExpired(credential, now = Date.now()) {
+  const exp = raccoonCredentialExpiresAtMs(credential);
+  return exp === undefined ? false : now >= exp;
+}
+
+/** 到期前提前量（默认 60s）：临期即刷新，避免请求正好撞在过期瞬间。 */
+export const RACCOON_REFRESH_SKEW_MS = 60_000;
+
+export function isRaccoonExpiringSoon(credential, now = Date.now(), skewMs = RACCOON_REFRESH_SKEW_MS) {
+  const exp = raccoonCredentialExpiresAtMs(credential);
+  return exp === undefined ? false : now + skewMs >= exp;
+}
+
+/** token 指纹：sha256 前 8 位十六进制。**唯一允许出现在日志/CLI 里的 token 表示**。 */
+export function raccoonTokenFingerprint(token) {
+  const s = String(token || "");
+  if (!s) return "";
+  try {
+    return createHash("sha256").update(s).digest("hex").slice(0, 8);
+  } catch {
+    return "";
+  }
+}
+
+/** uid 归一：优先 user_info 的 id，其次 office/userId，最后回退 token 指纹（保证非空且稳定）。 */
+export function resolveRaccoonUid({ userId = "", officeIdentity = "", token = "" } = {}) {
+  for (const candidate of [userId, officeIdentity]) {
+    const s = String(candidate || "").trim();
+    if (s) return s;
+  }
+  return raccoonTokenFingerprint(token);
+}