feishu-user-plugin 1.3.12 → 1.3.14

package/src/auth/env-backfill.js

@@ -0,0 +1,37 @@
+// src/auth/env-backfill.js — backfill `process.env.LARK_*` from canonical
+// credentials store, for legacy callers that read env directly.
+//
+// Motivation: v1.3.7+ canonical store is at ~/.feishu-user-plugin/credentials.json,
+// but the original CLI flows + e2e tests + dev probes (e.g. test-all.js,
+// test-comprehensive.js, scripts/probe-feishu-docx.js, scripts/test-wiki-attach-
+// fallback.js) constructed clients with `process.env.LARK_*`. After users move
+// creds to canonical, those env vars are empty in a fresh shell and the legacy
+// paths fall over.
+//
+// This helper sets process.env values from canonical if and only if they aren't
+// already set, preserving precedence: explicit shell env > canonical fallback.
+// Safe to call multiple times — idempotent. Safe to call before canonical
+// exists (no-op, legacy harness env still wins).
+
+'use strict';
+
+const SNAP_KEYS = [
+  'LARK_COOKIE',
+  'LARK_APP_ID',
+  'LARK_APP_SECRET',
+  'LARK_USER_ACCESS_TOKEN',
+  'LARK_USER_REFRESH_TOKEN',
+  'LARK_UAT_EXPIRES',
+];
+
+function backfillFromCanonical() {
+  try {
+    const { readCredentials } = require('./credentials');
+    const creds = readCredentials();
+    for (const k of SNAP_KEYS) {
+      if (!process.env[k] && creds[k]) process.env[k] = String(creds[k]);
+    }
+  } catch (_) { /* canonical may not exist; legacy path unaffected */ }
+}
+
+module.exports = { backfillFromCanonical, SNAP_KEYS };

package/src/auth/identity-state.js

@@ -84,7 +84,22 @@ function _refineIdentity(client, state) {
 // 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);
+    // v1.3.14 — explicit short-circuit when refreshUAT set `err.uatRevoked`.
+    // Lets refresh-side rejections (invalid_grant from /authen/v2/oauth/token)
+    // flow into the same UAT_REVOKED state as tool-call-side 20064 responses,
+    // and lets `withIdentityFallback` build a clear "请重跑 oauth" warning.
+    if (uatError.uatRevoked) {
+      return {
+        state: IdentityState.UAT_REVOKED,
+        viaReason: 'as user: refresh_token rejected by Feishu (invalid_grant)',
+      };
+    }
+    // v1.3.14 — redact base64-ish tokens (40+ chars of [A-Za-z0-9._-]) in
+    // case an upstream throw site leaked refresh_token or access_token bytes
+    // into the error message. Defense-in-depth on top of uat.js::refreshUAT
+    // which already avoids dumping the raw response body.
+    const rawMsg = uatError.message || String(uatError);
+    const msg = rawMsg.replace(/[A-Za-z0-9._-]{40,}/g, '<redacted>');
     // 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}` };
@@ -150,7 +165,12 @@ async function withIdentityFallback({ client, uatFn, botFn, label }) {
       uatErr = e;
     }
     if (uatResp && uatResp.code === 0) {
-      const data = { ...uatResp };
+      // Preserve the legacy _viaUser marker that 15+ _asUserOrApp callers read
+      // via `res._viaUser`. Without this flag, calendar/docs/bitable/wiki/okr/
+      // tasks/drive write tools labelled UAT-owned resources as viaUser:false,
+      // making users believe a bot created them. Caught by Codex review on
+      // PR #103 (P1 — set _viaUser on successful UAT results).
+      const data = { ...uatResp, _viaUser: true };
       return { data, via: 'uat', identity };
     }
     const cls = _classifyUatFailure(uatResp, uatErr);
@@ -201,4 +221,5 @@ module.exports = {
   invalidateIdentity,
   _refineIdentity, // exported for D's CredentialsMonitor hook (private API)
   _readInMemoryState, // exported for testing edge cases (private API)
+  _classifyUatFailure, // v1.3.14 — exported for testing redact + uatRevoked wiring
 };

package/src/auth/uat.js

@@ -28,13 +28,36 @@ const path = require('path');
 const os = require('os');
 const { fetchWithTimeout } = require('../utils');
 
+// One-warning-per-malformed-token tracker. Without this, a persistently bad
+// JWT would flood stderr every tool call (getValidUAT calls decode whenever
+// _uatExpires falsy, which it stays at 0 if decode returns 0). 1024-entry cap
+// is conservative — real tokens are rotated rarely; cap prevents OOM in the
+// unlikely event of a malformed-token spray.
+const _warnedMalformedTokens = new Set();
+function _markWarnedMalformedToken(token) {
+  if (typeof token !== 'string' || token.length === 0) return false;
+  const key = require('crypto').createHash('sha256').update(token, 'utf8').digest('hex').slice(0, 16);
+  if (_warnedMalformedTokens.has(key)) return false;
+  if (_warnedMalformedTokens.size >= 1024) _warnedMalformedTokens.clear();
+  _warnedMalformedTokens.add(key);
+  return true;
+}
+
 function decodeTokenExpiry(token) {
   try {
     const payload = token?.split('.')?.[1];
     if (!payload) return 0;
     const data = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
     return typeof data.exp === 'number' ? data.exp : 0;
-  } catch (_) {
+  } catch (e) {
+    // Log breadcrumb so silently-malformed UATs are observable, but only once
+    // per distinct bad token (hashed). We still return 0 (caller treats 0 as
+    // "never decoded — let refresh path decide") instead of throwing, because
+    // a bad JWT shouldn't crash tool dispatch — the next 99991663/99991668
+    // response will trigger refresh anyway.
+    if (_markWarnedMalformedToken(token)) {
+      console.error(`[feishu-user-plugin] decodeTokenExpiry: malformed JWT payload (${e.message}); will rely on Feishu rejection for refresh trigger`);
+    }
     return 0;
   }
 }
@@ -73,7 +96,12 @@ function adoptPersistedUATIfNewer(client) {
 }
 
 function uatLockPath() {
-  return path.join(os.homedir(), '.claude', 'feishu-uat-refresh.lock');
+  // v1.3.14: moved from ~/.claude/feishu-uat-refresh.lock to canonical
+  // ~/.feishu-user-plugin/ so Codex-only / non-Claude-Code users (whose
+  // ~/.claude/ may not exist) still get cross-process mutual exclusion.
+  // Mixed-version concern is N/A — running two different versions of this
+  // plugin in parallel is not a supported configuration.
+  return path.join(os.homedir(), '.feishu-user-plugin', 'uat-refresh.lock');
 }
 
 async function acquireRefreshLock(lockPath, { staleMs = 30000, pollMs = 200, timeoutMs = 20000 } = {}) {
@@ -105,13 +133,32 @@ function releaseRefreshLock(lockPath) {
 }
 
 async function refreshUAT(client) {
+  // v1.3.14 — Pre-lock cheap path: maybe a peer process already refreshed and
+  // persisted a valid token. Adopt it before paying for the file lock. This
+  // dramatically reduces lock contention in deployments with 10+ concurrent
+  // MCP server processes (one per Claude Code session).
+  let now = Math.floor(Date.now() / 1000);
+  if (adoptPersistedUATIfNewer(client) && client._uatExpires > now + 300) {
+    return client._uat;
+  }
+
   const lockPath = uatLockPath();
   const acquired = await acquireRefreshLock(lockPath);
   if (!acquired) {
-    console.error('[feishu-user-plugin] UAT refresh lock timed out; proceeding without mutual exclusion');
+    // Lock timed out (>20s of contention). Before falling through to an
+    // un-coordinated refresh — which can burn the refresh_token chain on the
+    // Feishu side — give disk one more chance: a peer may have written a
+    // fresh token between our pre-check and now.
+    now = Math.floor(Date.now() / 1000);
+    if (adoptPersistedUATIfNewer(client) && client._uatExpires > now + 300) {
+      return client._uat;
+    }
+    console.error('[feishu-user-plugin] UAT refresh lock timed out; proceeding without mutual exclusion (this may burn refresh_token chain — investigate if it happens often)');
   }
   try {
-    const now = Math.floor(Date.now() / 1000);
+    // Inside the lock: re-check disk one more time. Between acquireRefreshLock
+    // returning and this point, another holder may have released after writing.
+    now = Math.floor(Date.now() / 1000);
     if (adoptPersistedUATIfNewer(client) && client._uatExpires > now + 300) {
       return client._uat;
     }
@@ -128,7 +175,28 @@ async function refreshUAT(client) {
     });
     const data = await res.json();
     const tokenData = data.access_token ? data : data.data;
-    if (!tokenData?.access_token) throw new Error(`UAT refresh failed: ${JSON.stringify(data)}. Run: npx feishu-user-plugin oauth`);
+    if (!tokenData?.access_token) {
+      // v1.3.14 — never dump the raw response body. Some Feishu error paths
+      // echo back portions of the request including refresh_token bytes, and
+      // this message bubbles up to Error.message → MCP content[0].text →
+      // LLM transcript. Surface only the structured error code/msg.
+      const errCode = data?.error ?? data?.code ?? 'unknown';
+      const errMsg = data?.error_description ?? data?.msg ?? '(no error message from Feishu)';
+      // Distinguish refresh_token rejection (must re-oauth) from transient
+      // server-side errors so the identity state machine can flip to
+      // UAT_REVOKED, and withIdentityFallback can give the LLM clear guidance.
+      const isInvalidGrant = errCode === 'invalid_grant' || errCode === 20064;
+      if (isInvalidGrant) {
+        try {
+          const { _refineIdentity, IdentityState } = require('./identity-state');
+          _refineIdentity(client, IdentityState.UAT_REVOKED);
+        } catch (_) { /* identity-state may not be loaded in CLI subcommands; non-fatal */ }
+        const err = new Error('UAT refresh_token rejected by Feishu (invalid_grant). The 7-day refresh chain is broken. Run: npx feishu-user-plugin oauth to re-authorize.');
+        err.uatRevoked = true;
+        throw err;
+      }
+      throw new Error(`UAT refresh failed (code=${errCode}: ${errMsg}). If persistent, run: npx feishu-user-plugin oauth.`);
+    }
     client._uat = tokenData.access_token;
     client._uatRefresh = tokenData.refresh_token || client._uatRefresh;
     const expiresIn = typeof tokenData.expires_in === 'number' && tokenData.expires_in > 0 ? tokenData.expires_in : 7200;
@@ -164,9 +232,15 @@ async function withUAT(client, fn) {
   } catch (err) {
     const cls = classifyError(err);
     if (cls.action === 'retry') {
-      return fn(uat);
+      // v1.3.14 — fall through into the auth-code check below instead of
+      // returning the retry result raw. A token rotated between our first
+      // attempt and the retry (peer process refreshed) can manifest as a
+      // 99991663/99991668 in the retry response, and we want refreshUAT to
+      // run before bubbling that up as a hard failure.
+      data = await fn(uat);
+    } else {
+      throw err;
     }
-    throw err;
   }
 
   if (data.code === 99991668 || data.code === 99991663 || data.code === 99991677) {
@@ -242,4 +316,9 @@ module.exports = {
   asUserOrApp,
   persistUAT,
   adoptPersistedUATIfNewer,
+  // v1.3.14 — exposed for testing (lifecycle + race tests). Not part of the
+  // stable API; do not use outside src/test-* or scripts/test-* harnesses.
+  uatLockPath,
+  acquireRefreshLock,
+  releaseRefreshLock,
 };

package/src/cli.js

@@ -248,9 +248,10 @@ async function keepalive() {
       const needSwitch = all && prevActive !== profileName;
       try {
         if (needSwitch) cred.setActiveProfile(profileName);
-        // Set process.env so LarkOfficialClient.loadUAT() picks the right tokens
-        process.env.LARK_USER_ACCESS_TOKEN = env.LARK_USER_ACCESS_TOKEN;
-        process.env.LARK_USER_REFRESH_TOKEN = env.LARK_USER_REFRESH_TOKEN;
+        // v1.3.14 — direct field assignment is the source of truth; do NOT
+        // also set process.env (previous comment claimed LarkOfficialClient
+        // would read process.env, but loadUAT() is dead code and process.env
+        // pollution leaked between iterations of the --all loop).
         const official = new LarkOfficialClient(env.LARK_APP_ID, env.LARK_APP_SECRET);
         official._uat = env.LARK_USER_ACCESS_TOKEN;
         official._uatRefresh = env.LARK_USER_REFRESH_TOKEN;

package/src/clients/official/base.js

@@ -21,16 +21,21 @@ class LarkOfficialClient {
   }
 
   // --- UAT (User Access Token) Management ---
+  //
+  // v1.3.14 — preferred entry is src/server.js::loadUATFromEnv(client, env),
+  // which reads from a specific env block (credentials.json profile or harness
+  // env) rather than from process.env. `loadUAT()` below is kept for backward
+  // compat with `src/test-all.js` and any external callers, but new code in
+  // this repo should NOT use it — it can't see credentials.json profiles and
+  // doesn't participate in the profile-switch hot-reload path.
 
+  /** @deprecated v1.3.14 — use server.loadUATFromEnv(client, env) instead. */
   loadUAT() {
     const token = process.env.LARK_USER_ACCESS_TOKEN;
-    const refresh = process.env.LARK_USER_REFRESH_TOKEN;
-    const expires = parseInt(process.env.LARK_UAT_EXPIRES || '0');
-    if (token) {
-      this._uat = token;
-      this._uatRefresh = refresh || null;
-      this._uatExpires = expires || this._decodeTokenExpiry(token);
-    }
+    if (!token) return;
+    this._uat = token;
+    this._uatRefresh = process.env.LARK_USER_REFRESH_TOKEN || null;
+    this._uatExpires = parseInt(process.env.LARK_UAT_EXPIRES || '0') || this._decodeTokenExpiry(token);
   }
 
   get hasUAT() {
@@ -199,11 +204,36 @@ class LarkOfficialClient {
     // dispatching N redundant API calls per read_messages on hot chats.
     // has(id)==true / get(id)==null lets _computeDisplayLabel fall back to
     // "(open_id)" exactly the same way as before.
+    //
+    // PR #103 Copilot followup: getUserById / getAppName return null on
+    // non-zero Feishu codes (e.g. 99991672, scope missing) WITHOUT rejecting,
+    // so the per-batch Promise.allSettled rejection log misses these. Log
+    // the ids that ended without a name as a separate stderr line so failure
+    // shape is observable regardless of whether the underlying lookup
+    // returned null or rejected.
+    const unresolvedUserIds = [];
     for (const id of unknownUserIds) {
-      if (!this._userNameCache.has(id)) this._userNameCache.set(id, null);
+      if (!this._userNameCache.has(id) || this._userNameCache.get(id) === null) {
+        this._userNameCache.set(id, null);
+        unresolvedUserIds.push(id);
+      }
+    }
+    if (unresolvedUserIds.length) {
+      const sample = unresolvedUserIds.slice(0, 5).join(', ');
+      const tail = unresolvedUserIds.length > 5 ? ` (+${unresolvedUserIds.length - 5} more)` : '';
+      console.error(`[feishu-user-plugin] sender name unresolved (cached null) for ${unresolvedUserIds.length} id(s): ${sample}${tail}`);
     }
+    const unresolvedAppIds = [];
     for (const id of unknownAppIds) {
-      if (!this._appNameCache.has(id)) this._appNameCache.set(id, null);
+      if (!this._appNameCache.has(id) || this._appNameCache.get(id) === null) {
+        this._appNameCache.set(id, null);
+        unresolvedAppIds.push(id);
+      }
+    }
+    if (unresolvedAppIds.length) {
+      const sample = unresolvedAppIds.slice(0, 5).join(', ');
+      const tail = unresolvedAppIds.length > 5 ? ` (+${unresolvedAppIds.length - 5} more)` : '';
+      console.error(`[feishu-user-plugin] app name unresolved (cached null) for ${unresolvedAppIds.length} id(s): ${sample}${tail}`);
     }
 
     // Step 4: populate senderName, isExternal, displayLabel

package/src/error-codes.js

@@ -27,7 +27,8 @@ const FAILURE_MAP = {
   19001:  { action: 'uat', reason: 'bot_chat_not_found' },
 
   // UAT revoked — refresh_token explicitly invalid_grant (user revoked OAuth
-  // or 30-day window elapsed). The live trigger for this code lives in
+  // or the 7-day refresh_token window elapsed without any successful refresh
+  // to roll it forward). The live trigger for this code lives in
   // identity-state.js::_classifyUatFailure (UAT REST throws / returns 20064);
   // this entry exists for *symmetry* — should a bot-side surface ever return
   // 20064 (it shouldn't, bot uses app_access_token not refresh_token), the

package/src/oauth.js

@@ -16,6 +16,7 @@ const http = require('http');
 const { execSync } = require('child_process');
 const credentialsModule = require('./auth/credentials');
 const legacyConfig = require('./config');
+const { fetchWithTimeout } = require('./utils');
 
 // v1.3.9: profile-aware. Accepts `--profile <name>` (defaults to credentials.json::active);
 // reads APP_ID/SECRET from that profile, persists UAT back to that profile.
@@ -105,10 +106,11 @@ if (!APP_ID || !APP_SECRET) {
 async function getAppInfo() {
   try {
     // Get app_access_token to query app details
-    const tokenRes = await fetch('https://open.feishu.cn/open-apis/auth/v3/app_access_token/internal', {
+    const tokenRes = await fetchWithTimeout('https://open.feishu.cn/open-apis/auth/v3/app_access_token/internal', {
       method: 'POST',
       headers: { 'content-type': 'application/json' },
       body: JSON.stringify({ app_id: APP_ID, app_secret: APP_SECRET }),
+      timeoutMs: 10000,
     });
     const tokenData = await tokenRes.json();
     if (!tokenData.app_access_token) {
@@ -118,8 +120,9 @@ async function getAppInfo() {
 
     // Get app info — try the direct app query first, fall back to underauditlist
     let appName = null;
-    const directRes = await fetch(`https://open.feishu.cn/open-apis/application/v6/applications/${APP_ID}?lang=zh_cn`, {
+    const directRes = await fetchWithTimeout(`https://open.feishu.cn/open-apis/application/v6/applications/${APP_ID}?lang=zh_cn`, {
       headers: { 'Authorization': `Bearer ${tokenData.app_access_token}` },
+      timeoutMs: 10000,
     });
     const directData = await directRes.json();
     appName = directData?.data?.app?.app_name;
@@ -134,8 +137,9 @@ async function getAppInfo() {
       } else if (directData?.code && directData.code !== 0) {
         console.error(`[oauth] App name resolve failed: code=${directData.code} msg=${directData.msg}`);
       }
-      const listRes = await fetch('https://open.feishu.cn/open-apis/application/v6/applications/underauditlist?lang=zh_cn&page_size=1', {
+      const listRes = await fetchWithTimeout('https://open.feishu.cn/open-apis/application/v6/applications/underauditlist?lang=zh_cn&page_size=1', {
         headers: { 'Authorization': `Bearer ${tokenData.app_access_token}` },
+        timeoutMs: 10000,
       });
       const listData = await listRes.json();
       appName = listData?.data?.items?.[0]?.app_name;
@@ -156,17 +160,27 @@ async function exchangeCode(code) {
     code,
     redirect_uri: REDIRECT_URI,
   };
-  console.log('Token exchange request:', JSON.stringify({ ...body, client_secret: '***' }));
-  const tokenRes = await fetch('https://open.feishu.cn/open-apis/authen/v2/oauth/token', {
+  // v1.3.14 — redact `code` too: the authorization code is short-lived but
+  // it IS an exchangeable credential while it's still valid (~60s pre-exchange).
+  // Logging it to stdout means transcripts retain a usable credential window.
+  console.log('Token exchange request:', JSON.stringify({ ...body, client_secret: '***', code: '***' }));
+  const tokenRes = await fetchWithTimeout('https://open.feishu.cn/open-apis/authen/v2/oauth/token', {
     method: 'POST',
     headers: { 'content-type': 'application/json' },
     body: JSON.stringify(body),
+    timeoutMs: 15000,
   });
   const raw = await tokenRes.text();
-  console.log('Token exchange raw response:', raw.slice(0, 500));
+  // v1.3.13 security followup: don't log the full raw body — it contains the
+  // bare access_token + refresh_token. Log only the http status and a hint of
+  // success/failure; the parsed token never leaves this function except via
+  // saveToken (which writes the file with 0600 perms).
+  console.log(`Token exchange HTTP ${tokenRes.status} (body ${raw.length} bytes)`);
   let tokenData;
   try { tokenData = JSON.parse(raw); } catch (e) {
-    throw new Error(`Response not JSON: ${raw.slice(0, 200)}`);
+    // Parse error path: redact body in the thrown message so an upstream
+    // log line doesn't accidentally surface tokens.
+    throw new Error(`Response not JSON (HTTP ${tokenRes.status}, ${raw.length} bytes): ${raw.slice(0, 100).replace(/[A-Za-z0-9._-]{40,}/g, '<redacted>')}`);
   }
   if (tokenData.error) {
     throw new Error(`${tokenData.error}: ${tokenData.error_description}`);
@@ -199,8 +213,17 @@ function saveToken(tokenData) {
     if (ok) console.log(`Tokens written to ${profileLabel}`);
   }
   if (!ok) {
-    console.error('WARNING: Tokens could not be saved. Copy them manually:');
-    for (const [k, v] of Object.entries(updates)) console.error(`  ${k}=${v}`);
+    // v1.3.13 security followup: never dump full token bytes to stderr.
+    // Caller can find them by re-running OAuth or reading the credentials
+    // file. Show only the field shape so user knows what fields exist.
+    console.error('WARNING: Tokens could not be saved automatically. Re-run `npx feishu-user-plugin oauth` after fixing the config path, or check that `~/.feishu-user-plugin/credentials.json` is writable.');
+    console.error('Fields that would have been written (values redacted):');
+    for (const [k, v] of Object.entries(updates)) {
+      const preview = typeof v === 'string' && v.length > 0
+        ? `${v.slice(0, 6)}…(${v.length} chars)`
+        : '<empty>';
+      console.error(`  ${k}=${preview}`);
+    }
   }
 }
 
@@ -221,11 +244,15 @@ const server = http.createServer(async (req, res) => {
 
       const hasRefresh = !!tokenData.refresh_token;
       res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
+      // v1.3.14 — do not display any token bytes in the browser callback.
+      // Browser history / screenshots / OS screen recordings would otherwise
+      // retain the first 20 chars of the access token. Replaced with a length
+      // attestation so the user still sees the flow succeeded.
       res.end(`<h2>✅ 授权成功!</h2>
-<p>access_token: ${tokenData.access_token.slice(0, 20)}...</p>
+<p>access_token: ✅ 已获取（${tokenData.access_token.length} chars）</p>
 <p>scope: ${tokenData.scope}</p>
 <p>expires_in: ${tokenData.expires_in}s</p>
-<p>refresh_token: ${hasRefresh ? '✅ 已获取（30天有效，支持自动续期）' : '❌ 未返回（token 将在 2 小时后过期，需重新授权）'}</p>
+<p>refresh_token: ${hasRefresh ? '✅ 已获取（7天有效，支持自动续期；每次 refresh 滚动续 7 天）' : '❌ 未返回（token 将在 2 小时后过期，需重新授权）'}</p>
 <p>已保存到 MCP 配置文件，可以关闭此页面。</p>`);
 
       console.log('\n=== OAuth 授权成功 ===');

package/src/server.js

@@ -83,8 +83,15 @@ let nonOwnerPollTimer = null;
 let _ownerStartCallbacks = [];
 
 // Lark Desktop reactor state (v1.3.11 §A) — owned by the heartbeat callback.
+// v1.3.14 — `_lastSwitchAt = 0` was previously misinterpreted as "no recent
+// switch" by the lark-desktop reactor's debounce, so a cold-start owner that
+// hadn't observed any switch would still fire-on-first-tick if the snapshot
+// looked stale. We rebaseline `_lastSwitchAt` to the owner-claim wallclock on
+// first reactor invocation so the cold start window has the same debounce
+// budget as a long-running owner. See `_runLarkDesktopReactor` below.
 let _lastHashMtimes = {};
 let _lastSwitchAt = 0;
+let _reactorFirstTickDone = false;
 const _seenUnboundHashes = new Set();
 
 function _onBecomeOwner(cb) { _ownerStartCallbacks.push(cb); }
@@ -157,11 +164,14 @@ function getOfficialClient() {
   return officialClient;
 }
 
-// Mirror of LarkOfficialClient.loadUAT() but sourced from a specific env block
-// instead of process.env, so credentials.json profiles work uniformly. Also
-// the hot-reload entry point used by credMonitor.onUatChange: when `env` has
-// no UAT (user nuked the token), clear the in-memory copy instead of
+// UAT loader sourced from a specific env block (credentials.json profile or
+// harness env). Used both at startup and as the hot-reload entry point from
+// credMonitor.onUatChange. When `env` has no UAT (user nuked the token via
+// `oauth` --revoke or manual edit), clears the in-memory copy instead of
 // silently leaving the stale token in place.
+//
+// v1.3.14 — replaced the dead `LarkOfficialClient.loadUAT()` helper that
+// read from process.env. All UAT loading now goes through this function.
 function loadUATFromEnv(client, env) {
   const token = env?.LARK_USER_ACCESS_TOKEN || null;
   const refresh = env?.LARK_USER_REFRESH_TOKEN || null;
@@ -274,6 +284,14 @@ function _credMtime() {
 // the WS client with the new profile's events list).
 function _runLarkDesktopReactor() {
   const ld = require('./auth/lark-desktop');
+  // v1.3.14 — cold-start debounce: prevent the first reactor tick from
+  // treating a long-pre-existing snapshot as a "recent switch". By stamping
+  // _lastSwitchAt at first tick we give the debounce the same baseline as a
+  // long-running owner that just hot-took-over.
+  if (!_reactorFirstTickDone) {
+    _reactorFirstTickDone = true;
+    if (_lastSwitchAt === 0) _lastSwitchAt = Date.now();
+  }
   const out = ld.detectSwitch({
     prevSnapshot: _lastHashMtimes,
     lastSwitchAt: _lastSwitchAt,
@@ -332,6 +350,17 @@ credMonitor.onUatChange((env) => {
   console.error('[feishu-user-plugin] UAT reloaded from credentials.json (no restart needed)');
 });
 
+credMonitor.onCookieChange(() => {
+  // Cookie rotation: null the LarkUserClient singleton so the next
+  // getUserClient() call rebuilds it with the fresh cookie from env.
+  // Without this, cookie-based tools (send_to_user / search_contacts /
+  // get_login_status / send_as_user / batch_send) keep using the stale
+  // cookie until restart. PR #103 Codex P2 followup.
+  if (!userClient) return;
+  userClient = null;
+  console.error('[feishu-user-plugin] cookie rotation detected — userClient nulled, rebuilds on next tool call');
+});
+
 credMonitor.onCacheInvalidate(() => {
   if (officialClient) identityState.invalidateIdentity(officialClient);
 });
@@ -568,6 +597,11 @@ async function main() {
     }
   }
 
+  // Baseline credMonitor at startup so any credential changes between server
+  // boot and the first tool call fire hooks instead of being silently absorbed
+  // by the first sync()'s baselining branch. PR #103 Codex P2 followup.
+  credMonitor.sync();
+
   // --- Real-time events (v1.3.9 — owner-arbitrated) ---
   if (hasApp) {
     _claimAndStart().catch((e) => {

package/src/setup.js

@@ -102,10 +102,12 @@ async function main() {
   // Validate app credentials
   console.log('\nValidating app credentials...');
   try {
-    const res = await fetch('https://open.feishu.cn/open-apis/auth/v3/app_access_token/internal', {
+    const { fetchWithTimeout } = require('./utils');
+    const res = await fetchWithTimeout('https://open.feishu.cn/open-apis/auth/v3/app_access_token/internal', {
       method: 'POST',
       headers: { 'content-type': 'application/json' },
       body: JSON.stringify({ app_id: appId, app_secret: appSecret }),
+      timeoutMs: 10000,
     });
     const data = await res.json();
     if (data.app_access_token) {

package/src/test-all.js

@@ -4,6 +4,12 @@
  * Sends test messages to "飞书plugin测试群".
  */
 require('dotenv').config({ path: require('path').join(__dirname, '..', '.env') });
+
+// v1.3.14 — backfill process.env from canonical credentials store so
+// `npm test` works for users who moved creds to ~/.feishu-user-plugin/.
+// See src/auth/env-backfill.js for full rationale.
+require('./auth/env-backfill').backfillFromCanonical();
+
 const { LarkUserClient } = require('./clients/user');
 const { LarkOfficialClient } = require('./clients/official');
 
@@ -333,6 +339,11 @@ main().catch(console.error).finally(() => {
     console.error('with-uat-retry: FAIL', e);
     process.exitCode = 1;
   });
+  require('./test-uat-lifecycle').run().catch(e => {
+    console.error('uat-lifecycle: FAIL', e);
+    process.exitCode = 1;
+  });
+  require('./test-cookie-heartbeat').run();
   require('./test-populate-sender-names').run().catch(e => {
     console.error('populate-sender-names: FAIL', e);
     process.exitCode = 1;
@@ -363,5 +374,6 @@ main().catch(console.error).finally(() => {
     process.exitCode = 1;
   });
   require('./test-cli-tool').run();
+  require('./test-lark-desktop').run();
   require('./test-display-label');  // standalone — runs on require, exits non-zero on fail
 });

package/src/test-comprehensive.js

@@ -1,10 +1,14 @@
 #!/usr/bin/env node
 /**
  * Comprehensive test: exercises every tool category in feishu-user-plugin.
- * Reads credentials from .env, tests each layer independently.
+ * Reads credentials from .env, then backfills from canonical store. Tests
+ * each layer independently.
  */
 const path = require('path');
 require('dotenv').config({ path: path.join(__dirname, '..', '.env') });
+// v1.3.14 — let users on canonical store run this without exporting env vars
+// or maintaining a stale .env. .env still wins via dotenv when present.
+require('./auth/env-backfill').backfillFromCanonical();
 
 const { LarkUserClient } = require('./clients/user');
 const { LarkOfficialClient } = require('./clients/official');
@@ -274,7 +278,8 @@ async function testUAT() {
 }
 
 async function main() {
-  console.log('=== feishu-user-plugin v1.1.3 — Comprehensive Test ===\n');
+  const pkgVersion = require('../package.json').version;
+  console.log(`=== feishu-user-plugin v${pkgVersion} — Comprehensive Test ===\n`);
 
   await testUserIdentity();
   console.log('');