feishu-user-plugin 1.3.10 → 1.3.12

package/src/auth/credentials-monitor.js

@@ -0,0 +1,185 @@
+// src/auth/credentials-monitor.js — single poller for credentials.json changes.
+//
+// The MCP server is long-lived; users routinely re-run `npx feishu-user-plugin
+// oauth` from another shell to refresh UAT, expecting the running server to
+// pick up the new token. Pre-v1.3.12 only the active-profile field was
+// observed (server.js::_syncActiveProfileFromDisk); UAT changes, cookie
+// rotations, and cache invalidation all required a Claude Code restart.
+//
+// CredentialsMonitor unifies the polling: per-tool-call `sync()` stats the
+// file, hashes its contents, and fires per-field hooks on diff. Owners
+// (officialClient, userClient, _userNameCache) register hooks at boot.
+//
+// Hash strategy: we don't trust mtime alone because `touch` would falsely
+// trigger a UAT reload across every dispatcher call. Content hash + mtime
+// means: skip the read entirely when mtime unchanged (cheap path), and
+// when mtime advanced compute SHA-256 of the active profile's fields and
+// compare per-field hashes to decide which hooks fire.
+//
+// Design choices:
+//   - factory not singleton: `createCredentialsMonitor({ path? })` so tests
+//     can use a tmpdir and server.js wires one against the real path.
+//   - synchronous sync(): callers are the request dispatcher; we can't await
+//     before handling a tool call. fs.statSync + fs.readFileSync are fine —
+//     credentials.json is tiny (a few KiB max).
+//   - hooks fire synchronously in registration order; exceptions are logged
+//     to stderr and don't block other hooks.
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+
+const DEFAULT_PATH = path.join(os.homedir(), '.feishu-user-plugin', 'credentials.json');
+
+function _hash(s) {
+  return crypto.createHash('sha256').update(s, 'utf8').digest('hex').slice(0, 16);
+}
+
+function _readSafely(p) {
+  try { return fs.readFileSync(p, 'utf8'); } catch (_) { return null; }
+}
+
+function _statSafely(p) {
+  try { return fs.statSync(p); } catch (_) { return null; }
+}
+
+function _parseSafely(s) {
+  try {
+    const o = JSON.parse(s);
+    if (o && typeof o === 'object' && o.profiles && o.active) return o;
+  } catch (_) {}
+  return null;
+}
+
+function _activeProfileEnv(canonical) {
+  if (!canonical) return null;
+  const p = canonical.profiles[canonical.active];
+  return p ? { ...p } : null;
+}
+
+function _fieldHash(env, key) {
+  if (!env || env[key] === undefined || env[key] === null) return null;
+  return _hash(String(env[key]));
+}
+
+function createCredentialsMonitor({ path: credPath = DEFAULT_PATH } = {}) {
+  const hooks = {
+    uat: [],
+    cookie: [],
+    profile: [],
+    invalidate: [],
+  };
+
+  // Baseline state: null until first successful sync().
+  let lastMtimeMs = null;
+  let lastActive = null;
+  let lastUatHash = null;
+  let lastCookieHash = null;
+  // refresh field is paired with UAT — refresh-only rotation also fires uat hook.
+  let lastRefreshHash = null;
+  // `_initialized` flips on first successful read. We DON'T reset on file
+  // disappearance — that way a user who briefly removes credentials.json
+  // (e.g. by hand-editing in vim with backup file shenanigans) doesn't see
+  // the next reappear treated as a silent rebaseline.
+  let _initialized = false;
+
+  function _fire(list, arg, label) {
+    for (const cb of list) {
+      try { cb(arg); } catch (e) {
+        console.error(`[feishu-user-plugin] credentials-monitor ${label} hook threw: ${e.message}`);
+      }
+    }
+  }
+
+  function sync() {
+    const stat = _statSafely(credPath);
+    if (!stat) {
+      // File missing — early return. We don't reset state because the file
+      // may reappear and we want to diff against what we last saw.
+      lastMtimeMs = null; // force re-read on reappear (mtime will differ)
+      return;
+    }
+    // Cheap exit when mtime hasn't advanced.
+    if (lastMtimeMs !== null && stat.mtimeMs === lastMtimeMs) return;
+
+    const raw = _readSafely(credPath);
+    if (raw === null) { lastMtimeMs = stat.mtimeMs; return; }
+    const canonical = _parseSafely(raw);
+    if (!canonical) { lastMtimeMs = stat.mtimeMs; return; }
+
+    const env = _activeProfileEnv(canonical);
+    const active = canonical.active;
+    const uatHash = _fieldHash(env, 'LARK_USER_ACCESS_TOKEN');
+    const cookieHash = _fieldHash(env, 'LARK_COOKIE');
+    const refreshHash = _fieldHash(env, 'LARK_USER_REFRESH_TOKEN');
+
+    // First observation establishes baseline silently.
+    const baselining = !_initialized;
+    lastMtimeMs = stat.mtimeMs;
+    _initialized = true;
+
+    if (baselining) {
+      lastActive = active;
+      lastUatHash = uatHash;
+      lastCookieHash = cookieHash;
+      lastRefreshHash = refreshHash;
+      return;
+    }
+
+    let anyChange = false;
+    if (active !== lastActive) {
+      anyChange = true;
+      const prev = lastActive;
+      lastActive = active;
+      _fire(hooks.profile, { from: prev, to: active, env }, 'profile');
+    }
+    if (uatHash !== lastUatHash || refreshHash !== lastRefreshHash) {
+      anyChange = true;
+      lastUatHash = uatHash;
+      lastRefreshHash = refreshHash;
+      _fire(hooks.uat, env, 'uat');
+    }
+    if (cookieHash !== lastCookieHash) {
+      anyChange = true;
+      lastCookieHash = cookieHash;
+      _fire(hooks.cookie, env, 'cookie');
+    }
+    if (anyChange) {
+      _fire(hooks.invalidate, env, 'invalidate');
+    }
+  }
+
+  // Force-fire all hooks as if everything changed. Used by switch_profile
+  // when it wants to short-circuit the mtime debounce.
+  function forceInvalidate() {
+    const stat = _statSafely(credPath);
+    const raw = stat ? _readSafely(credPath) : null;
+    const canonical = raw ? _parseSafely(raw) : null;
+    const env = _activeProfileEnv(canonical) || {};
+    _fire(hooks.profile, { from: lastActive, to: canonical?.active, env }, 'profile');
+    _fire(hooks.uat, env, 'uat');
+    _fire(hooks.cookie, env, 'cookie');
+    _fire(hooks.invalidate, env, 'invalidate');
+    if (canonical) {
+      lastActive = canonical.active;
+      lastUatHash = _fieldHash(env, 'LARK_USER_ACCESS_TOKEN');
+      lastCookieHash = _fieldHash(env, 'LARK_COOKIE');
+      lastRefreshHash = _fieldHash(env, 'LARK_USER_REFRESH_TOKEN');
+      lastMtimeMs = stat.mtimeMs;
+    }
+  }
+
+  return {
+    sync,
+    forceInvalidate,
+    onUatChange:    (cb) => { hooks.uat.push(cb); },
+    onCookieChange: (cb) => { hooks.cookie.push(cb); },
+    onProfileSwitch: (cb) => { hooks.profile.push(cb); },
+    onCacheInvalidate: (cb) => { hooks.invalidate.push(cb); },
+  };
+}
+
+module.exports = { createCredentialsMonitor };

package/src/auth/credentials.js

@@ -360,6 +360,51 @@ function setProfileEvents(name, eventList) {
   return true;
 }
 
+// --- Lark Desktop hash bindings (v1.3.11 §A) ---
+//
+// Each profile may carry an optional `larkHash` 32-char-hex field binding it
+// to one of `~/Library/Containers/com.bytedance.macos.feishu/.../sdk_storage/<hash>/`.
+// The owner heartbeat reactor uses this binding to decide which profile to
+// switch to when the user changes account in Lark Desktop. See
+// src/auth/lark-desktop.js for the detection / switch logic; this module
+// just owns the persisted binding.
+
+const _LARK_HASH_RE = /^[a-f0-9]{32}$/;
+
+function getProfileLarkHash(name) {
+  const f = _readFile();
+  const target = name || (f ? f.active : 'default');
+  if (f && f.profiles[target] && typeof f.profiles[target].larkHash === 'string') {
+    return f.profiles[target].larkHash;
+  }
+  return null;
+}
+
+function setProfileLarkHash(name, hash) {
+  if (hash !== null && (typeof hash !== 'string' || !_LARK_HASH_RE.test(hash))) {
+    throw new Error('setProfileLarkHash: hash must be 32-char hex (a-f, 0-9) or null');
+  }
+  const f = _readFile();
+  if (!f) throw new Error('No credentials.json — cannot set profile larkHash. Run `npx feishu-user-plugin migrate --confirm` first.');
+  if (!f.profiles[name]) {
+    throw new Error(`setProfileLarkHash: profile "${name}" not found. Available: ${Object.keys(f.profiles).join(', ')}`);
+  }
+  if (hash === null) delete f.profiles[name].larkHash;
+  else f.profiles[name].larkHash = hash;
+  _atomicWriteJson(_credentialsPath(), f);
+  return true;
+}
+
+function findProfileByHash(hash) {
+  if (typeof hash !== 'string' || !_LARK_HASH_RE.test(hash)) return null;
+  const f = _readFile();
+  if (!f) return null;
+  for (const [name, profile] of Object.entries(f.profiles)) {
+    if (profile.larkHash === hash) return name;
+  }
+  return null;
+}
+
 // --- Profile hints (v1.3.8) ---
 //
 // profileHints maps resourceKey → profileName, persisted in credentials.json.
@@ -419,6 +464,10 @@ module.exports = {
   // per-profile events list (v1.3.9 A.4)
   getProfileEvents,
   setProfileEvents,
+  // Lark Desktop hash bindings (v1.3.11 §A)
+  getProfileLarkHash,
+  setProfileLarkHash,
+  findProfileByHash,
   // profile hints (v1.3.8)
   getProfileHints,
   setProfileHint,

package/src/auth/identity-state.js

@@ -0,0 +1,204 @@
+// src/auth/identity-state.js — identity state machine for UAT-first/bot-fallback flows.
+//
+// The v1.3.7 pattern was `asUserOrApp` in src/auth/uat.js: try UAT, catch any
+// failure, retry with bot, and attach a string `_fallbackWarning`. That works
+// but is opaque: the caller can't tell whether UAT was revoked (need to
+// re-oauth), expired (will refresh on next call), missing scope (need admin),
+// or just experienced a network blip. The 2026-05 incident showed how this
+// hides "UAT revoked for weeks" because every tool silently retried bot.
+//
+// This module adds a first-class IdentityState enum + a reactive cache. Each
+// call to withIdentityFallback returns `{ data, via, viaReason, identity }`;
+// LLMs and the get_login_status diagnostic can read the identity directly
+// instead of grepping warning strings.
+//
+// Cache: keyed by appId (one entry per LarkOfficialClient instance is enough
+// in practice — clients aren't shared across appIds in this codebase, but
+// keying by appId is the safe contract). 30 second TTL. Refined writes from
+// withIdentityFallback bypass TTL and write through immediately.
+//
+// What it owns:
+//   - IdentityState enum
+//   - resolveIdentity(client) — reads in-memory state into a state value
+//   - withIdentityFallback({client, uatFn, botFn, label}) — composable wrapper
+//   - invalidateIdentity(client) — cache eviction (CredentialsMonitor hook)
+
+'use strict';
+
+const IdentityState = Object.freeze({
+  VALID_USER:        'VALID_USER',
+  UAT_EXPIRED:       'UAT_EXPIRED',
+  UAT_REVOKED:       'UAT_REVOKED',
+  UAT_MISSING_SCOPE: 'UAT_MISSING_SCOPE',
+  BOT_ONLY:          'BOT_ONLY',
+  NO_CREDENTIALS:    'NO_CREDENTIALS',
+});
+
+const CACHE_TTL_MS = 30_000;
+const _cache = new Map(); // key = client.appId — value = { state, expiresAt }
+
+function _key(client) {
+  // Fall back to a sentinel for clients without appId so NO_CREDENTIALS is still cacheable.
+  return client?.appId || '__no_app__';
+}
+
+function _readInMemoryState(client) {
+  if (!client) return IdentityState.NO_CREDENTIALS;
+  const hasApp = !!client.appId;
+  const hasUAT = !!client.hasUAT;
+  if (!hasUAT && !hasApp) return IdentityState.NO_CREDENTIALS;
+  if (!hasUAT) return IdentityState.BOT_ONLY;
+  // hasUAT true — distinguish VALID_USER vs UAT_EXPIRED by expiry timestamp.
+  // expires=0 means "we never decoded — treat as valid and let the refresh
+  // path decide". Negative expiry never occurs but is treated as expired.
+  const now = Math.floor(Date.now() / 1000);
+  if (client._uatExpires && client._uatExpires > 0 && client._uatExpires <= now) {
+    return IdentityState.UAT_EXPIRED;
+  }
+  return IdentityState.VALID_USER;
+}
+
+async function resolveIdentity(client) {
+  const k = _key(client);
+  const cached = _cache.get(k);
+  if (cached && cached.expiresAt > Date.now()) return cached.state;
+  const state = _readInMemoryState(client);
+  _cache.set(k, { state, expiresAt: Date.now() + CACHE_TTL_MS });
+  return state;
+}
+
+function invalidateIdentity(client) {
+  _cache.delete(_key(client));
+}
+
+// Write a refined state through to the cache (bypasses TTL). Called when
+// withIdentityFallback observes a definitive UAT failure (revoked, missing
+// scope) — the cache should reflect what we just learned, not what was
+// inferred from in-memory state alone.
+function _refineIdentity(client, state) {
+  _cache.set(_key(client), { state, expiresAt: Date.now() + CACHE_TTL_MS });
+}
+
+// Classify a UAT-side failure into a refined IdentityState + a human-readable
+// via_reason string. Returns null if the failure isn't auth-related (caller
+// should keep the original VALID_USER state and just record the via_reason).
+function _classifyUatFailure(uatResp, uatError) {
+  if (uatError) {
+    const msg = uatError.message || String(uatError);
+    // Network/JSON parse errors don't refine identity — UAT is still presumed
+    // valid, we just couldn't reach Feishu this call.
+    return { state: null, viaReason: `as user: ${msg}` };
+  }
+  if (!uatResp || typeof uatResp !== 'object') return null;
+  const code = uatResp.code;
+  const detail = `as user: code=${code} msg=${uatResp.msg}`;
+  switch (code) {
+    case 20064:    return { state: IdentityState.UAT_REVOKED,       viaReason: detail };
+    case 99991663: return { state: IdentityState.UAT_EXPIRED,       viaReason: detail };
+    case 99991668: return { state: IdentityState.UAT_MISSING_SCOPE, viaReason: detail };
+    case 99991677: return { state: IdentityState.UAT_EXPIRED,       viaReason: detail };
+    default:       return { state: null,                            viaReason: detail };
+  }
+}
+
+function _buildFallbackWarning({ identity, viaReason, hadUAT }) {
+  if (!hadUAT) {
+    // BOT_ONLY — the caller never configured UAT. Strictly speaking this
+    // isn't a "fallback" (no UAT attempt was made), but we keep the
+    // informational warning because users frequently *think* they configured
+    // UAT and are surprised to find resources owned by the shared bot. Same
+    // wording as the legacy asUserOrApp path so existing get_login_status
+    // expectations don't shift.
+    return `⚠️  未配置 UAT,本次操作以 bot 身份执行。资源归属于共享 bot「Claude聊天助手」,不是你。想让资源归你所有,先跑 \`npx feishu-user-plugin oauth\` 然后重启 Claude Code / Codex。`;
+  }
+  let hint;
+  switch (identity) {
+    case IdentityState.UAT_REVOKED:
+      hint = 'UAT 已被撤销 (invalid_grant)';
+      break;
+    case IdentityState.UAT_MISSING_SCOPE:
+      hint = 'UAT 缺少所需 scope';
+      break;
+    case IdentityState.UAT_EXPIRED:
+      hint = 'UAT 已过期';
+      break;
+    default:
+      hint = 'UAT 不可用';
+      break;
+  }
+  return `⚠️  ${hint} (${viaReason}),本次操作以 bot 身份执行。资源归属于共享 bot「Claude聊天助手」,不是你。恢复方法:运行 \`npx feishu-user-plugin oauth\` 后重启 Claude Code / Codex。`;
+}
+
+// withIdentityFallback({ client, uatFn, botFn, label })
+//
+// Tries uatFn first (when client has UAT), classifies any failure, then runs
+// botFn. Returns `{ data, via, viaReason?, identity, fallbackWarning? }`.
+// Throws an Error with `.uatSummary` and `.botError` when both sides fail.
+async function withIdentityFallback({ client, uatFn, botFn, label }) {
+  if (!label) throw new Error('withIdentityFallback: label is required (for error messages)');
+
+  let identity = await resolveIdentity(client);
+  const hadUAT = !!client?.hasUAT;
+  let uatSummary = null;
+
+  if (hadUAT) {
+    let uatResp = null;
+    let uatErr = null;
+    try {
+      uatResp = await uatFn();
+    } catch (e) {
+      uatErr = e;
+    }
+    if (uatResp && uatResp.code === 0) {
+      const data = { ...uatResp };
+      return { data, via: 'uat', identity };
+    }
+    const cls = _classifyUatFailure(uatResp, uatErr);
+    uatSummary = cls?.viaReason || `as user: unknown failure`;
+    if (cls?.state) {
+      identity = cls.state;
+      _refineIdentity(client, cls.state);
+    }
+    // fall through to bot
+  }
+
+  // Bot path
+  let botData;
+  let botError;
+  try {
+    botData = await botFn();
+  } catch (e) {
+    botError = e;
+  }
+
+  if (botError) {
+    if (uatSummary) {
+      const err = new Error(`${label} failed on both identities. ${uatSummary}. as app: ${botError.message}`);
+      err.uatSummary = uatSummary;
+      err.botError = botError;
+      err.identity = identity;
+      throw err;
+    }
+    throw botError;
+  }
+
+  // Decorate the bot response with via metadata + (when UAT was attempted) a
+  // fallback warning the caller can surface to the LLM.
+  const data = { ...botData };
+  data._viaUser = false;
+  const fallbackWarning = _buildFallbackWarning({ identity, viaReason: uatSummary, hadUAT });
+  if (fallbackWarning) data._fallbackWarning = fallbackWarning;
+  const out = { data, via: 'bot', identity };
+  if (uatSummary) out.viaReason = uatSummary;
+  if (fallbackWarning) out.fallbackWarning = fallbackWarning;
+  return out;
+}
+
+module.exports = {
+  IdentityState,
+  resolveIdentity,
+  withIdentityFallback,
+  invalidateIdentity,
+  _refineIdentity, // exported for D's CredentialsMonitor hook (private API)
+  _readInMemoryState, // exported for testing edge cases (private API)
+};

package/src/auth/lark-desktop.js

@@ -0,0 +1,135 @@
+// src/auth/lark-desktop.js — Lark Desktop sdk_storage detection (v1.3.11 §A).
+//
+// macOS-only: Linux/Windows return null from getSdkStorageDir() and all
+// callers no-op gracefully. We never read the encrypted cookie_store.db —
+// only stat its mtime to detect account switches. Profile↔hash bindings
+// live in credentials.json::profiles[*].larkHash.
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const HASH_RE = /^[a-f0-9]{32}$/;
+
+// Debounce + freshness windows for the heartbeat reactor.
+const SWITCH_DEBOUNCE_MS = 5_000;
+const UNBOUND_FRESH_WINDOW_MS = 60_000;
+
+function _macSdkStorageDir() {
+  return path.join(
+    os.homedir(),
+    'Library/Containers/com.bytedance.macos.feishu/Data/Library/Application Support/LarkShell/sdk_storage'
+  );
+}
+
+function getSdkStorageDir() {
+  if (process.platform !== 'darwin') return null;
+  const dir = _macSdkStorageDir();
+  try {
+    return fs.statSync(dir).isDirectory() ? dir : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+// List Lark account hash directories under sdk_storage, sorted by
+// cookie_store.db mtime descending. Hash dirs without a cookie_store.db
+// are filtered (account never logged in / cleared).
+//
+// Returns: [{ hash, mtimeMs, dir }]
+function listAccountHashes({ dir } = {}) {
+  const root = dir || getSdkStorageDir();
+  if (!root) return [];
+  let entries;
+  try { entries = fs.readdirSync(root); } catch (_) { return []; }
+  const out = [];
+  for (const name of entries) {
+    if (!HASH_RE.test(name)) continue;
+    const accountDir = path.join(root, name);
+    const dbPath = path.join(accountDir, 'cookie_store.db');
+    let mtimeMs;
+    try { mtimeMs = fs.statSync(dbPath).mtimeMs; } catch (_) { continue; }
+    out.push({ hash: name, mtimeMs, dir: accountDir });
+  }
+  out.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  return out;
+}
+
+function mostRecentHash(opts = {}) {
+  const list = listAccountHashes(opts);
+  return list.length > 0 ? list[0] : null;
+}
+
+// Pure-ish reactor logic, dependency-injected for unit tests.
+//
+// Inputs:
+//   prevSnapshot: { [hash]: mtimeMs } from the previous heartbeat
+//   lastSwitchAt: ms timestamp of the last auto-switch (debounce key)
+//   seenUnboundHashes: Set<hash> — emit hint once per hash per session
+//   credsApi: { getActiveProfileName, getProfileLarkHash, findProfileByHash }
+//   listFn: () => [...] — defaults to listAccountHashes() with auto-detected dir
+//   now: ms — defaults to Date.now()
+//   log: (msg) => void — defaults to console.error (the unbound-hash hint goes here)
+//
+// Returns:
+//   { switchTo: { hash, profile } | null, isUnbound: boolean, hash?: string }
+//
+// Mutates seenUnboundHashes (adds the hash when it emits a hint).
+function detectSwitch({
+  prevSnapshot,
+  lastSwitchAt,
+  seenUnboundHashes,
+  credsApi,
+  listFn,
+  now,
+  log,
+} = {}) {
+  if (!credsApi) credsApi = require('./credentials');
+  if (!listFn) listFn = () => listAccountHashes();
+  if (typeof now !== 'number') now = Date.now();
+  if (typeof log !== 'function') log = console.error;
+
+  if (now - lastSwitchAt < SWITCH_DEBOUNCE_MS) {
+    return { switchTo: null, isUnbound: false };
+  }
+
+  const list = listFn();
+  if (list.length === 0) return { switchTo: null, isUnbound: false };
+
+  const top = list[0];
+  const activeProfile = credsApi.getActiveProfileName();
+  const activeHash = credsApi.getProfileLarkHash(activeProfile);
+  if (top.hash === activeHash) return { switchTo: null, isUnbound: false };
+
+  // Only act on a true mtime advance — this prevents repeatedly switching
+  // when the snapshot baseline shows a stable older delta.
+  const prev = prevSnapshot[top.hash] || 0;
+  if (top.mtimeMs <= prev) return { switchTo: null, isUnbound: false };
+
+  const targetProfile = credsApi.findProfileByHash(top.hash);
+  if (!targetProfile) {
+    const isFresh = (now - top.mtimeMs) < UNBOUND_FRESH_WINDOW_MS;
+    if (isFresh && seenUnboundHashes && !seenUnboundHashes.has(top.hash)) {
+      seenUnboundHashes.add(top.hash);
+      log(
+        `[feishu-user-plugin] Lark Desktop active account hash ${top.hash} is not bound to any MCP profile. ` +
+        `Run: npx feishu-user-plugin setup --profile <name> --bind-hash ${top.hash}`
+      );
+    }
+    return { switchTo: null, isUnbound: true, hash: top.hash };
+  }
+
+  return { switchTo: { hash: top.hash, profile: targetProfile }, isUnbound: false };
+}
+
+module.exports = {
+  HASH_RE,
+  SWITCH_DEBOUNCE_MS,
+  UNBOUND_FRESH_WINDOW_MS,
+  getSdkStorageDir,
+  listAccountHashes,
+  mostRecentHash,
+  detectSwitch,
+};