feishu-user-plugin 1.3.13 → 1.3.15

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}` };
@@ -206,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,17 +133,42 @@ 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;
     }
     if (!client._uatRefresh) throw new Error('UAT expired and no refresh token. Run: npx feishu-user-plugin oauth');
+    // Snapshot the refresh_token we are about to send BEFORE awaiting. A peer
+    // in-process refresh or the credentials monitor can hot-reload
+    // client._uatRefresh during the round-trip; the invalid_grant self-heal
+    // below must compare against the token actually sent, not a field that may
+    // have already rotated. (Codex review, PR #111.)
+    const attemptedRefresh = client._uatRefresh;
     const res = await fetchWithTimeout('https://open.feishu.cn/open-apis/authen/v2/oauth/token', {
       method: 'POST',
       headers: { 'content-type': 'application/json' },
@@ -123,12 +176,64 @@ async function refreshUAT(client) {
         grant_type: 'refresh_token',
         client_id: client.appId,
         client_secret: client.appSecret,
-        refresh_token: client._uatRefresh,
+        refresh_token: attemptedRefresh,
       }),
     });
     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) {
+        // v1.3.15 — self-heal a benign refresh_token rotation race before
+        // declaring the 7-day chain dead. When cross-process mutual exclusion
+        // is defeated (lock-acquire timeout fallthrough above, or a transient
+        // mixed-version upgrade window where old/new instances use different
+        // lock paths), two processes can refresh with the same refresh_token;
+        // Feishu rotates it for the winner and rejects the loser with
+        // invalid_grant. By the time the loser lands here, the winner has very
+        // likely already persisted a fresh, valid, DIFFERENT token to disk.
+        // Re-read disk: if it now holds a different, still-valid token, our
+        // invalid_grant just means "our copy was rotated away" — adopt it and
+        // recover, instead of flipping to UAT_REVOKED and pushing the user
+        // through a needless `oauth` re-consent (the "授权操作通知 没撑过一晚上"
+        // symptom). Only when disk still holds the SAME (now-dead) refresh_token
+        // is this a genuine revocation. Covered by test-uat-lifecycle
+        // "invalid_grant + peer rotated fresh token to disk".
+        now = Math.floor(Date.now() / 1000);
+        // Best-effort re-sync from disk (a no-op if a peer/monitor already
+        // updated this client in memory). Then recover iff we now hold a
+        // DIFFERENT, still-valid token than the one we actually sent — this
+        // covers both the cross-process race (disk holds the winner) and the
+        // in-process / hot-reload race (client already holds the winner).
+        // Gating on the resulting client state, rather than on
+        // adoptPersistedUATIfNewer()'s return value, is what lets the
+        // hot-reload case recover (adopt is a no-op there). (Codex review, PR #111.)
+        adoptPersistedUATIfNewer(client);
+        if (client._uat
+            && client._uatRefresh !== attemptedRefresh
+            && client._uatExpires > now + 300) {
+          console.error('[feishu-user-plugin] UAT invalid_grant on the sent refresh_token; a different valid token is present (peer won the rotation) — adopted, no re-consent needed');
+          return client._uat;
+        }
+        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 +269,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 +353,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() {

package/src/clients/official/docs.js

@@ -63,6 +63,22 @@ module.exports = {
     return { items: res.data.items || [] };
   },
 
+  // Direct children of a single block — scoped, so it does not inherit the
+  // whole-document 500-block cap of getDocBlocks. Used by createDocTable to map
+  // a table's cells (and each cell's text block) reliably in large documents.
+  async getBlockChildren(documentId, blockId) {
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/docx/v1/documents/${documentId}/blocks/${blockId}/children`,
+      query: { page_size: '500' },
+      sdkFn: () => this.client.docx.documentBlockChildren.get({
+        path: { document_id: documentId, block_id: blockId },
+        params: { page_size: 500 },
+      }),
+      label: 'getBlockChildren',
+    });
+    return { items: res.data.items || [] };
+  },
+
   async createDocBlock(documentId, parentBlockId, children, index) {
     const data = { children };
     if (index !== undefined) data.index = index;
@@ -79,6 +95,85 @@ module.exports = {
     return { blocks: res.data.children || [], fallbackWarning: res._fallbackWarning || null };
   },
 
+  // Create a Feishu docx table (block_type=31) and optionally fill its cells —
+  // so callers never have to know docx block types. Added after field reports
+  // of agents guessing the table block_type (40 is wrong; 31 table / 32 cell).
+  // Flow:
+  //   1) create the table block with row_size/column_size — Feishu auto-creates
+  //      the table_cell (32) children (row-major) and gives each cell an empty
+  //      text block.
+  //   2) read the table back to map cell_id -> its auto-created text block.
+  //   3) fill: UPDATE each cell's existing text block (clean — no stray empty
+  //      block) when present, else CREATE a text block in the cell.
+  // `cells` is an optional row-major 2D array of plain strings.
+  // Returns { tableBlockId, cells:[[cellId,...],...], rows, columns, filled, viaUser, fallbackWarning }.
+  async createDocTable(documentId, parentBlockId, { rows, columns, cells, columnWidth, headerRow, headerColumn, index } = {}) {
+    rows = Number(rows); columns = Number(columns);
+    if (!Number.isInteger(rows) || !Number.isInteger(columns) || rows < 1 || columns < 1) {
+      throw new Error('createDocTable: rows and columns must be integers >= 1');
+    }
+    const property = { row_size: rows, column_size: columns };
+    if (Array.isArray(columnWidth) && columnWidth.length === columns) property.column_width = columnWidth;
+    if (headerRow) property.header_row = true;
+    if (headerColumn) property.header_column = true;
+    const createBody = { children: [{ block_type: 31, table: { property } }] };
+    if (index !== undefined) createBody.index = index;
+    const created = await this._asUserOrApp({
+      uatPath: `/open-apis/docx/v1/documents/${documentId}/blocks/${parentBlockId}/children`,
+      method: 'POST',
+      body: createBody,
+      sdkFn: () => this.client.docx.documentBlockChildren.create({
+        path: { document_id: documentId, block_id: parentBlockId },
+        data: createBody,
+      }),
+      label: 'createDocTable',
+    });
+    const tableCreated = (created.data.children || [])[0];
+    const tableBlockId = tableCreated?.block_id;
+    if (!tableBlockId) throw new Error(`createDocTable: no table block_id returned: ${JSON.stringify(created.data).slice(0, 400)}`);
+    const viaUser = !!created._viaUser;
+    const fallbackWarning = created._fallbackWarning || null;
+
+    // Resolve the cell IDs. Prefer the create response; else fetch the table
+    // block's children directly (scoped — NOT the whole-doc getDocBlocks, which
+    // caps at 500 blocks and would silently lose an appended table's cells in a
+    // large document). Fail loud rather than silently dropping requested content.
+    let flatCellIds = tableCreated.table?.cells || tableCreated.children || [];
+    if (flatCellIds.length < rows * columns) {
+      flatCellIds = ((await this.getBlockChildren(documentId, tableBlockId)).items || []).map(b => b.block_id);
+    }
+    if (flatCellIds.length < rows * columns) {
+      throw new Error(`createDocTable: created table ${tableBlockId} but resolved only ${flatCellIds.length}/${rows * columns} cells — aborting fill to avoid silently dropping content.`);
+    }
+    const grid = [];
+    for (let r = 0; r < rows; r++) grid.push(flatCellIds.slice(r * columns, (r + 1) * columns));
+
+    let filled = 0;
+    if (Array.isArray(cells)) {
+      for (let r = 0; r < rows; r++) {
+        for (let c = 0; c < columns; c++) {
+          const content = cells[r] ? cells[r][c] : undefined;
+          if (content === undefined || content === null || content === '') continue;
+          const cellId = grid[r][c];
+          if (!cellId) throw new Error(`createDocTable: missing cell id at row ${r}, col ${c}`);
+          // Each fresh cell auto-creates exactly one empty text block — UPDATE it
+          // (clean) rather than CREATE a second. Scoped per-cell fetch stays
+          // correct regardless of overall document size.
+          const cellChildren = (await this.getBlockChildren(documentId, cellId)).items || [];
+          const textChild = cellChildren.find(b => b.block_type === 2);
+          const elements = { elements: [{ text_run: { content: String(content) } }] };
+          if (textChild) {
+            await this.updateDocBlock(documentId, textChild.block_id, { update_text_elements: elements });
+          } else {
+            await this.createDocBlock(documentId, cellId, [{ block_type: 2, text: elements }]);
+          }
+          filled++;
+        }
+      }
+    }
+    return { tableBlockId, cells: grid, rows, columns, filled, viaUser, fallbackWarning };
+  },
+
   async updateDocBlock(documentId, blockId, updateBody) {
     const res = await this._asUserOrApp({
       uatPath: `/open-apis/docx/v1/documents/${documentId}/blocks/${blockId}`,

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,11 +160,15 @@ 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();
   // v1.3.13 security followup: don't log the full raw body — it contains the
@@ -236,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,

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');
 
@@ -316,6 +322,10 @@ async function main() {
 main().catch(console.error).finally(() => {
   // Fixture-based unit test — runs regardless of credential availability
   require('./test-read-doc-markdown').run();
+  require('./test-doc-table').run().catch(e => {
+    console.error('doc-table: FAIL', e);
+    process.exitCode = 1;
+  });
   require('./test-switch-profile').run().catch(e => {
     console.error('switch-profile-e2e: FAIL', e);
     process.exitCode = 1;
@@ -333,6 +343,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;

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('');