feishu-user-plugin 1.3.13 → 1.3.15

package/src/test-uat-lifecycle.js

@@ -0,0 +1,449 @@
+#!/usr/bin/env node
+// Unit tests for the UAT lifecycle building blocks in src/auth/uat.js.
+// Covers v1.3.14 hardening:
+//   - decodeTokenExpiry: malformed JWT → 0 with stderr breadcrumb (no throw)
+//   - acquireRefreshLock: basic acquire / contention timeout / stale recovery
+//   - releaseRefreshLock: tolerant of already-released
+//   - adoptPersistedUATIfNewer: peer-rotation adoption logic
+//   - refreshUAT: invalid_grant → err.uatRevoked = true (via mocked fetch)
+//   - refreshUAT: success path persists + adopts new token
+//
+// These are pure-unit; no live Feishu calls.
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const assert = require('assert');
+
+let pass = 0;
+let fail = 0;
+
+function ok(name, fn) {
+  try {
+    const r = fn();
+    if (r && typeof r.then === 'function') {
+      return r.then(() => { console.log(`  OK  ${name}`); pass++; },
+                    (e) => { console.log(`  FAIL ${name}: ${e.message}`); fail++; });
+    }
+    console.log(`  OK  ${name}`);
+    pass++;
+  } catch (e) {
+    console.log(`  FAIL ${name}: ${e.message}`);
+    fail++;
+  }
+}
+
+async function run() {
+  console.log('=== test-uat-lifecycle ===');
+
+  const uat = require('./auth/uat');
+
+  // --- decodeTokenExpiry ---
+  await ok('decodeTokenExpiry: well-formed JWT returns exp', () => {
+    // Hand-craft a JWT with exp=123456 (no signature; we only read payload).
+    const payload = Buffer.from(JSON.stringify({ exp: 123456 }), 'utf8').toString('base64url');
+    const token = `header.${payload}.sig`;
+    assert.strictEqual(uat.decodeTokenExpiry(token), 123456);
+  });
+
+  await ok('decodeTokenExpiry: missing payload returns 0', () => {
+    assert.strictEqual(uat.decodeTokenExpiry('only-header'), 0);
+  });
+
+  await ok('decodeTokenExpiry: malformed base64 returns 0 (with stderr breadcrumb)', () => {
+    // Capture stderr so the breadcrumb doesn't pollute test output. We don't
+    // assert on the message — just that the function doesn't throw and returns 0.
+    const origErr = console.error;
+    const captured = [];
+    console.error = (...args) => captured.push(args.join(' '));
+    try {
+      const v = uat.decodeTokenExpiry('header.not-base64-payload!!.sig');
+      assert.strictEqual(v, 0);
+      // We don't strictly require a breadcrumb (silent return 0 was the v1.3.13
+      // behavior; v1.3.14 added stderr log). Test passes either way.
+    } finally {
+      console.error = origErr;
+    }
+  });
+
+  await ok('decodeTokenExpiry: payload without exp returns 0', () => {
+    const payload = Buffer.from(JSON.stringify({ sub: 'u_xxx' }), 'utf8').toString('base64url');
+    assert.strictEqual(uat.decodeTokenExpiry(`h.${payload}.s`), 0);
+  });
+
+  // v1.3.14 — flood-gate test: a persistently-malformed JWT should only log
+  // once per distinct token, not on every call. Without the gate, every
+  // getValidUAT call (= every UAT-backed tool dispatch) flooded stderr.
+  await ok('decodeTokenExpiry: same malformed token logs only once across repeated calls', () => {
+    const origErr = console.error;
+    const captured = [];
+    console.error = (...args) => captured.push(args.join(' '));
+    try {
+      const badToken = 'header.malformed-payload-XX-not-base64.sig-1';
+      for (let i = 0; i < 5; i++) uat.decodeTokenExpiry(badToken);
+      const decodeWarnings = captured.filter(l => /decodeTokenExpiry: malformed/.test(l));
+      assert.strictEqual(decodeWarnings.length, 1,
+        `expected exactly 1 decode warning for the same bad token across 5 calls; got ${decodeWarnings.length}: ${JSON.stringify(decodeWarnings)}`);
+    } finally {
+      console.error = origErr;
+    }
+  });
+
+  await ok('decodeTokenExpiry: different malformed tokens each log once', () => {
+    const origErr = console.error;
+    const captured = [];
+    console.error = (...args) => captured.push(args.join(' '));
+    try {
+      uat.decodeTokenExpiry('header.bad-A!!!XX.sig');
+      uat.decodeTokenExpiry('header.bad-B@@@YY.sig');
+      uat.decodeTokenExpiry('header.bad-C###ZZ.sig');
+      const decodeWarnings = captured.filter(l => /decodeTokenExpiry: malformed/.test(l));
+      assert.strictEqual(decodeWarnings.length, 3,
+        `expected one warning per distinct bad token; got ${decodeWarnings.length}`);
+    } finally {
+      console.error = origErr;
+    }
+  });
+
+  // --- acquireRefreshLock / releaseRefreshLock ---
+
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'test-uat-lifecycle-'));
+  const lockPath = path.join(tmpDir, 'test.lock');
+
+  await ok('acquireRefreshLock: fresh dir, lock acquires', async () => {
+    const got = await uat.acquireRefreshLock(lockPath, { timeoutMs: 1000 });
+    assert.strictEqual(got, true);
+    assert.strictEqual(fs.existsSync(lockPath), true);
+    uat.releaseRefreshLock(lockPath);
+    assert.strictEqual(fs.existsSync(lockPath), false);
+  });
+
+  await ok('acquireRefreshLock: contention times out', async () => {
+    const got1 = await uat.acquireRefreshLock(lockPath, { timeoutMs: 1000 });
+    assert.strictEqual(got1, true);
+    try {
+      const got2 = await uat.acquireRefreshLock(lockPath, { timeoutMs: 500, pollMs: 100, staleMs: 60_000 });
+      assert.strictEqual(got2, false, 'second acquire should fail while first holds');
+    } finally {
+      uat.releaseRefreshLock(lockPath);
+    }
+  });
+
+  await ok('acquireRefreshLock: stale lock recovers', async () => {
+    // Write a "stale" lock by setting mtime in the past.
+    fs.writeFileSync(lockPath, `${process.pid}\n${Date.now() - 60_000}\n`);
+    const oldTime = Date.now() - 60_000;
+    fs.utimesSync(lockPath, oldTime / 1000, oldTime / 1000);
+    // staleMs=5s — our lock is 60s old, should be detected and stolen.
+    const got = await uat.acquireRefreshLock(lockPath, { timeoutMs: 2000, staleMs: 5_000, pollMs: 100 });
+    assert.strictEqual(got, true, 'should steal stale lock');
+    uat.releaseRefreshLock(lockPath);
+  });
+
+  await ok('releaseRefreshLock: tolerant of already-released', () => {
+    // Should not throw.
+    uat.releaseRefreshLock(lockPath);
+    uat.releaseRefreshLock(path.join(tmpDir, 'never-existed.lock'));
+  });
+
+  // --- adoptPersistedUATIfNewer ---
+  //
+  // Uses a tmp HOME so we don't touch the real canonical store. We monkey-patch
+  // os.homedir to point at our tmp.
+
+  const fakeHome = fs.mkdtempSync(path.join(os.tmpdir(), 'fake-home-'));
+  fs.mkdirSync(path.join(fakeHome, '.feishu-user-plugin'), { recursive: true, mode: 0o700 });
+  const fakeCanonical = path.join(fakeHome, '.feishu-user-plugin', 'credentials.json');
+  const origHomedir = os.homedir;
+  os.homedir = () => fakeHome;
+
+  // Snapshot + clear LARK_* env vars so legacy fallback inside readCredentials
+  // can't pick them up from the host process. Pre-v1.3.14 these tests passed
+  // standalone but failed in `npm test` because test-all.js v1.3.14 backfill
+  // populates process.env from the real canonical store.
+  const SNAP_KEYS = ['LARK_COOKIE', 'LARK_APP_ID', 'LARK_APP_SECRET',
+                     'LARK_USER_ACCESS_TOKEN', 'LARK_USER_REFRESH_TOKEN',
+                     'LARK_UAT_EXPIRES', 'LARK_UAT_SCOPE', 'LARK_PROFILES_JSON'];
+  const envSnapshot = {};
+  for (const k of SNAP_KEYS) { envSnapshot[k] = process.env[k]; delete process.env[k]; }
+
+  function writeCanonical(env) {
+    fs.writeFileSync(fakeCanonical, JSON.stringify({
+      version: 1,
+      active: 'default',
+      profiles: { default: env },
+      profileHints: {},
+    }, null, 2));
+    fs.chmodSync(fakeCanonical, 0o600);
+  }
+
+  try {
+    await ok('adoptPersistedUATIfNewer: no canonical → false', () => {
+      // ensure no file
+      try { fs.unlinkSync(fakeCanonical); } catch (_) {}
+      const client = { _uat: null, _uatRefresh: null, _uatExpires: 0 };
+      const r = uat.adoptPersistedUATIfNewer(client);
+      assert.strictEqual(r, false);
+    });
+
+    await ok('adoptPersistedUATIfNewer: same token → false', () => {
+      writeCanonical({
+        LARK_USER_ACCESS_TOKEN: 'same.token.value',
+        LARK_USER_REFRESH_TOKEN: 'same.refresh.value',
+        LARK_UAT_EXPIRES: 5000,
+      });
+      const client = { _uat: 'same.token.value', _uatRefresh: 'same.refresh.value', _uatExpires: 5000 };
+      const r = uat.adoptPersistedUATIfNewer(client);
+      assert.strictEqual(r, false);
+    });
+
+    await ok('adoptPersistedUATIfNewer: newer access token → adopts', () => {
+      writeCanonical({
+        LARK_USER_ACCESS_TOKEN: 'new.access.token',
+        LARK_USER_REFRESH_TOKEN: 'old.refresh',
+        LARK_UAT_EXPIRES: 9999,
+      });
+      const client = { _uat: 'old.access', _uatRefresh: 'old.refresh', _uatExpires: 5000 };
+      const r = uat.adoptPersistedUATIfNewer(client);
+      assert.strictEqual(r, true);
+      assert.strictEqual(client._uat, 'new.access.token');
+      assert.strictEqual(client._uatExpires, 9999);
+    });
+
+    await ok('adoptPersistedUATIfNewer: rotated refresh_token → adopts', () => {
+      writeCanonical({
+        LARK_USER_ACCESS_TOKEN: 'same.access',
+        LARK_USER_REFRESH_TOKEN: 'rotated.refresh',
+        LARK_UAT_EXPIRES: 5000,
+      });
+      const client = { _uat: 'same.access', _uatRefresh: 'old.refresh', _uatExpires: 5000 };
+      const r = uat.adoptPersistedUATIfNewer(client);
+      assert.strictEqual(r, true);
+      assert.strictEqual(client._uatRefresh, 'rotated.refresh');
+    });
+  } finally {
+    os.homedir = origHomedir;
+    // Restore the LARK_* env vars we cleared for this test.
+    for (const k of SNAP_KEYS) {
+      if (envSnapshot[k] === undefined) delete process.env[k];
+      else process.env[k] = envSnapshot[k];
+    }
+  }
+
+  // --- refreshUAT: invalid_grant → err.uatRevoked = true ---
+  //
+  // Monkey-patch global.fetch to simulate Feishu refresh responses without
+  // touching the network. fetchWithTimeout in utils.js delegates to global.fetch.
+
+  await ok('refreshUAT: invalid_grant throws err.uatRevoked=true', async () => {
+    os.homedir = () => fakeHome;
+    writeCanonical({
+      LARK_USER_ACCESS_TOKEN: 'expired.token',
+      LARK_USER_REFRESH_TOKEN: 'dead.refresh',
+      LARK_UAT_EXPIRES: Math.floor(Date.now() / 1000) - 3600, // 1h ago
+    });
+
+    const origFetch = global.fetch;
+    global.fetch = async () => ({
+      json: async () => ({ error: 'invalid_grant', error_description: 'refresh_token expired' }),
+    });
+
+    try {
+      const client = {
+        appId: 'test', appSecret: 'test',
+        _uat: 'expired.token',
+        _uatRefresh: 'dead.refresh',
+        _uatExpires: Math.floor(Date.now() / 1000) - 3600,
+      };
+      let thrown = null;
+      try {
+        await uat.refreshUAT(client);
+      } catch (e) {
+        thrown = e;
+      }
+      assert.ok(thrown, 'refreshUAT should throw');
+      assert.strictEqual(thrown.uatRevoked, true, 'err.uatRevoked must be true');
+      assert.ok(thrown.message.includes('invalid_grant') || thrown.message.includes('refresh_token'),
+                `error message should reference invalid_grant: ${thrown.message}`);
+      // Critically: error message must NOT contain the raw response body /
+      // refresh_token bytes. v1.3.14 redact regression guard.
+      assert.ok(!thrown.message.includes('dead.refresh'), 'error message must not echo refresh_token');
+    } finally {
+      global.fetch = origFetch;
+      os.homedir = origHomedir;
+    }
+  });
+
+  // --- refreshUAT: benign rotation race must self-heal, not false-revoke ---
+  //
+  // A peer process wins the refresh_token rotation and persists a fresh, VALID
+  // token to disk DURING our refresh round-trip; our now-stale refresh_token
+  // then comes back invalid_grant. refreshUAT must adopt the peer's on-disk
+  // token and recover, instead of throwing uatRevoked (which would push the
+  // user through a needless `npx feishu-user-plugin oauth` re-consent — the
+  // root cause of the "授权操作通知 没撑过一晚上" reports).
+  await ok('refreshUAT: invalid_grant + peer rotated fresh token to disk → adopts & recovers (no false revoke)', async () => {
+    os.homedir = () => fakeHome;
+    const now = Math.floor(Date.now() / 1000);
+    // Disk starts equal to our stale in-memory token so the pre-fetch adopt
+    // checks find nothing newer and we proceed into the refresh fetch.
+    writeCanonical({
+      LARK_USER_ACCESS_TOKEN: 'stale.access',
+      LARK_USER_REFRESH_TOKEN: 'stale.refresh',
+      LARK_UAT_EXPIRES: String(now - 3600),
+    });
+
+    const origFetch = global.fetch;
+    global.fetch = async () => {
+      // The winning peer finishes mid-round-trip: persists a fresh VALID token.
+      writeCanonical({
+        LARK_USER_ACCESS_TOKEN: 'winner.access',
+        LARK_USER_REFRESH_TOKEN: 'winner.refresh',
+        LARK_UAT_EXPIRES: String(now + 7200),
+      });
+      // Our stale refresh_token was rotated away on the Feishu side.
+      return { json: async () => ({ error: 'invalid_grant', error_description: 'refresh_token expired' }) };
+    };
+
+    try {
+      const client = {
+        appId: 'test', appSecret: 'test',
+        _uat: 'stale.access',
+        _uatRefresh: 'stale.refresh',
+        _uatExpires: now - 3600,
+      };
+      let thrown = null, ret = null;
+      try { ret = await uat.refreshUAT(client); } catch (e) { thrown = e; }
+      assert.ok(!thrown, `should recover, not throw; got: ${thrown && thrown.message}`);
+      assert.strictEqual(ret, 'winner.access', 'should return the peer-rotated access token');
+      assert.strictEqual(client._uatRefresh, 'winner.refresh', 'should adopt the peer-rotated refresh_token');
+    } finally {
+      global.fetch = origFetch;
+      os.homedir = origHomedir;
+    }
+  });
+
+  // Codex review (PR #111) edge: a peer in-process refresh / credentials-monitor
+  // hot-reloads THIS client in memory (and persists to disk) WHILE our refresh
+  // request — carrying the now-stale token — is still in flight. Because we
+  // snapshot the sent token before awaiting and gate recovery on client state
+  // (not adoptPersistedUATIfNewer's return value), we must still recover instead
+  // of false-revoking. With the pre-fix code (post-await capture) this throws.
+  await ok('refreshUAT: invalid_grant after mid-flight hot-reload to a fresh token → recovers (no false revoke)', async () => {
+    os.homedir = () => fakeHome;
+    const now = Math.floor(Date.now() / 1000);
+    // Disk starts stale so the pre-fetch adopt checks proceed into the fetch.
+    writeCanonical({
+      LARK_USER_ACCESS_TOKEN: 'stale.access',
+      LARK_USER_REFRESH_TOKEN: 'stale.refresh',
+      LARK_UAT_EXPIRES: String(now - 3600),
+    });
+    const client = {
+      appId: 'test', appSecret: 'test',
+      _uat: 'stale.access', _uatRefresh: 'stale.refresh', _uatExpires: now - 3600,
+    };
+
+    const origFetch = global.fetch;
+    global.fetch = async () => {
+      // Concurrent winner finishes mid-flight: persists rotated token to disk
+      // AND a hot-reload updates this very client in memory.
+      writeCanonical({
+        LARK_USER_ACCESS_TOKEN: 'winner.access',
+        LARK_USER_REFRESH_TOKEN: 'winner.refresh',
+        LARK_UAT_EXPIRES: String(now + 7200),
+      });
+      client._uat = 'winner.access';
+      client._uatRefresh = 'winner.refresh';
+      client._uatExpires = now + 7200;
+      return { json: async () => ({ error: 'invalid_grant', error_description: 'refresh_token expired' }) };
+    };
+
+    try {
+      let thrown = null, ret = null;
+      try { ret = await uat.refreshUAT(client); } catch (e) { thrown = e; }
+      assert.ok(!thrown, `should recover, not throw; got: ${thrown && thrown.message}`);
+      assert.strictEqual(ret, 'winner.access', 'should recover the winner token despite mid-flight hot-reload');
+    } finally {
+      global.fetch = origFetch;
+      os.homedir = origHomedir;
+    }
+  });
+
+  // identity-state.js redact-regex regression guard. Exercises the actual
+  // regex on `_classifyUatFailure` path that the previous "no dead.refresh"
+  // assertion in test #14 did NOT cover (the invalid_grant message is
+  // hard-coded with no interpolation, so it's trivially redacted).
+  await ok('identity-state _classifyUatFailure: redact regex strips long token-like strings from uatError.message', () => {
+    const { _classifyUatFailure } = require('./auth/identity-state');
+    // A realistic-looking JWT-like base64-ish string > 40 chars.
+    const longToken = 'eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3Nzk0MDAwMDB9.abc123def456ghi789jklmnoXYZabcdefgXXXX';
+    assert.ok(longToken.length >= 40, 'fixture token should be >= 40 chars to trigger redact');
+    const fakeErr = new Error(`UAT request failed: server returned: ${longToken}`);
+    const cls = _classifyUatFailure(null, fakeErr);
+    assert.ok(cls, 'should classify a uatError');
+    assert.ok(!cls.viaReason.includes(longToken), `viaReason must not contain raw long token; got: ${cls.viaReason}`);
+    assert.ok(cls.viaReason.includes('<redacted>'), `viaReason must contain '<redacted>' marker; got: ${cls.viaReason}`);
+    assert.strictEqual(cls.state, null, 'non-uatRevoked errors should not refine identity from this path');
+  });
+
+  await ok('identity-state _classifyUatFailure: uatRevoked flag short-circuits to UAT_REVOKED state', () => {
+    const { _classifyUatFailure, IdentityState } = require('./auth/identity-state');
+    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;
+    const cls = _classifyUatFailure(null, err);
+    assert.strictEqual(cls.state, IdentityState.UAT_REVOKED, 'uatRevoked flag must refine state to UAT_REVOKED');
+    assert.ok(cls.viaReason.includes('invalid_grant') || cls.viaReason.includes('rejected'),
+              `viaReason must mention rejection: ${cls.viaReason}`);
+  });
+
+  await ok('refreshUAT: non-invalid_grant error does NOT set uatRevoked', async () => {
+    os.homedir = () => fakeHome;
+    writeCanonical({
+      LARK_USER_ACCESS_TOKEN: 'expired.token',
+      LARK_USER_REFRESH_TOKEN: 'live.refresh',
+      LARK_UAT_EXPIRES: Math.floor(Date.now() / 1000) - 3600,
+    });
+
+    const origFetch = global.fetch;
+    global.fetch = async () => ({
+      json: async () => ({ code: 99991663, msg: 'token transient error' }),
+    });
+
+    try {
+      const client = {
+        appId: 'test', appSecret: 'test',
+        _uat: 'expired.token',
+        _uatRefresh: 'live.refresh',
+        _uatExpires: Math.floor(Date.now() / 1000) - 3600,
+      };
+      let thrown = null;
+      try {
+        await uat.refreshUAT(client);
+      } catch (e) {
+        thrown = e;
+      }
+      assert.ok(thrown, 'should throw on non-success');
+      assert.ok(!thrown.uatRevoked, 'transient error should not set uatRevoked');
+      assert.ok(thrown.message.includes('99991663') || thrown.message.includes('transient'),
+                `should mention specific error: ${thrown.message}`);
+    } finally {
+      global.fetch = origFetch;
+      os.homedir = origHomedir;
+    }
+  });
+
+  // --- Cleanup ---
+  try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch (_) {}
+  try { fs.rmSync(fakeHome, { recursive: true, force: true }); } catch (_) {}
+
+  console.log(`\n=== test-uat-lifecycle: ${pass} passed, ${fail} failed ===`);
+  if (fail > 0) process.exit(1);
+}
+
+if (require.main === module) {
+  run().catch((e) => { console.error('test-uat-lifecycle harness error:', e); process.exit(1); });
+}
+
+module.exports = { run };

package/src/tools/docs.js

@@ -52,7 +52,7 @@ const schemas = [
   },
   {
     name: 'manage_doc_block',
-    description: '[Official API] Manage content blocks in a document. Single tool replaces v1.3.6 create_doc_block / update_doc_block / delete_doc_blocks.\n  action=create — five modes:\n    (A) Generic — pass `children` array (e.g. [{block_type:2, text:{...}}]).\n    (B) Image from local file — pass `image_path`; plugin uploads and patches.\n    (C) Image from token — pass `image_token` (already uploaded).\n    (D) File attachment from local file — pass `file_path`; plugin handles VIEW-wrap + replace_file.\n    (E) File from token — pass `file_token`.\n  action=update — generic (pass `update_body`), image-replace (pass `image_token`), or file-replace (pass `file_token`).\n  action=delete — pass `parent_block_id` + `start_index` + `end_index` (range delete).\n`document_id` accepts native ID, wiki node token, or Feishu URL.',
+    description: '[Official API] Manage content blocks in a document. Single tool replaces v1.3.6 create_doc_block / update_doc_block / delete_doc_blocks.\n  action=create — six modes (pass exactly ONE):\n    (A) Generic — pass `children` array (e.g. [{block_type:2, text:{...}}]).\n    (B) Image from local file — pass `image_path`; plugin uploads and patches.\n    (C) Image from token — pass `image_token` (already uploaded).\n    (D) File attachment from local file — pass `file_path`; plugin handles VIEW-wrap + replace_file.\n    (E) File from token — pass `file_token`.\n    (F) Table — pass `table={rows,columns,cells?}`; plugin creates a block_type=31 table (Feishu auto-makes the block_type=32 cells) and fills each provided cell. USE THIS for tables — do NOT hand-build table blocks via `children` (the table block_type is 31, NOT 40; getting it wrong returns invalid_param).\n  action=update — generic (pass `update_body`), image-replace (pass `image_token`), or file-replace (pass `file_token`).\n  action=delete — pass `parent_block_id` + `start_index` + `end_index` (range delete).\n`document_id` accepts native ID, wiki node token, or Feishu URL.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -69,6 +69,7 @@ const schemas = [
         file_path: { type: 'string', description: 'Local file path — create mode D (mutually exclusive with other create modes).' },
         file_token: { type: 'string', description: 'Pre-uploaded docx file token — create mode E, or update file-replace.' },
         update_body: { type: 'object', description: 'Generic update payload for action=update. E.g. {update_text_elements:{elements:[{text_run:{content:"new text"}}]}}.' },
+        table: { type: 'object', description: 'Create a table — create mode F (mutually exclusive with other create modes). Shape: {rows:int>=1, columns:int>=1, cells?:string[][] (row-major plain text; omit/empty-string to leave a cell blank), column_width?:int[] (px, length=columns), header_row?:bool, header_column?:bool}. The plugin creates a block_type=31 table, lets Feishu auto-create the cells, and fills each provided cell by updating its text — you never specify block types. Returns {tableBlockId, cells:[[cellId,...]] (row-major grid), filled}. Example: {"rows":2,"columns":2,"cells":[["Name","Role"],["Ann","PM"]]}.' },
       },
       required: ['action', 'document_id'],
     },
@@ -121,8 +122,16 @@ const handlers = {
     switch (args.action) {
       case 'create': {
         need(args.parent_block_id, 'parent_block_id', 'create');
-        const modes = [args.children, args.image_path, args.image_token, args.file_path, args.file_token].filter(Boolean);
-        if (modes.length > 1) return text('manage_doc_block(create): pass exactly ONE of children / image_path / image_token / file_path / file_token.');
+        const modes = [args.children, args.image_path, args.image_token, args.file_path, args.file_token, args.table].filter(Boolean);
+        if (modes.length > 1) return text('manage_doc_block(create): pass exactly ONE of children / image_path / image_token / file_path / file_token / table.');
+        if (args.table) {
+          const t = args.table;
+          return json(await official.createDocTable(docId, args.parent_block_id, {
+            rows: t.rows, columns: t.columns, cells: t.cells,
+            columnWidth: t.column_width, headerRow: t.header_row, headerColumn: t.header_column,
+            index: args.index,
+          }));
+        }
         if (args.image_path || args.image_token) {
           const r = await official.createDocBlockWithImage(docId, args.parent_block_id, {
             imagePath: args.image_path,
@@ -139,7 +148,7 @@ const handlers = {
           });
           return json(r);
         }
-        if (!args.children) return text('manage_doc_block(create): children, image_path, image_token, file_path, or file_token is required.');
+        if (!args.children) return text('manage_doc_block(create): children, image_path, image_token, file_path, file_token, or table is required.');
         return json(await official.createDocBlock(docId, args.parent_block_id, args.children, args.index));
       }
       case 'update': {

package/src/oauth-auto.js

@@ -1,175 +0,0 @@
-#!/usr/bin/env node
-// DEV ONLY: Automated OAuth using local Playwright (not used in production).
-// Uses .env directly; not migrated to config module.
-// Requires: npm install playwright (not in package.json dependencies)
-const http = require('http');
-const { chromium } = require('playwright');
-const fs = require('fs');
-const path = require('path');
-const dotenv = require('dotenv');
-
-dotenv.config({ path: path.join(__dirname, '..', '.env') });
-
-const APP_ID = process.env.LARK_APP_ID;
-const APP_SECRET = process.env.LARK_APP_SECRET;
-const COOKIE_STR = process.env.LARK_COOKIE;
-const PORT = 9997;
-const REDIRECT_URI = `http://127.0.0.1:${PORT}/callback`;
-const SCOPES = 'offline_access im:message im:message:readonly im:chat:readonly contact:user.base:readonly';
-
-function parseCookies(cookieStr) {
-  return cookieStr.split(';').map(c => {
-    const [name, ...rest] = c.trim().split('=');
-    return { name: name.trim(), value: rest.join('=').trim(), domain: '.feishu.cn', path: '/' };
-  }).filter(c => c.name && c.value);
-}
-
-function saveToken(tokenData) {
-  const envPath = path.join(__dirname, '..', '.env');
-  let envContent = '';
-  try { envContent = fs.readFileSync(envPath, 'utf8'); } catch {}
-  const updates = {
-    LARK_USER_ACCESS_TOKEN: tokenData.access_token,
-    LARK_USER_REFRESH_TOKEN: tokenData.refresh_token || '',
-    LARK_UAT_SCOPE: tokenData.scope || '',
-    LARK_UAT_EXPIRES: String(Math.floor(Date.now() / 1000 + (typeof tokenData.expires_in === 'number' && tokenData.expires_in > 0 ? tokenData.expires_in : 7200))),
-  };
-  for (const [key, val] of Object.entries(updates)) {
-    const regex = new RegExp(`^${key}=.*$`, 'm');
-    if (regex.test(envContent)) {
-      envContent = envContent.replace(regex, `${key}=${val}`);
-    } else {
-      envContent += `\n${key}=${val}`;
-    }
-  }
-  fs.writeFileSync(envPath, envContent.trim() + '\n');
-}
-
-async function exchangeCode(code) {
-  console.log('[token] Exchanging code via v2...');
-  const res = await fetch('https://open.feishu.cn/open-apis/authen/v2/oauth/token', {
-    method: 'POST',
-    headers: { 'content-type': 'application/json' },
-    body: JSON.stringify({ grant_type: 'authorization_code', client_id: APP_ID, client_secret: APP_SECRET, code, redirect_uri: REDIRECT_URI }),
-  });
-  const raw = await res.text();
-  console.log('[token] Response:', raw.slice(0, 300));
-  const data = JSON.parse(raw);
-  if (data.access_token) return data;
-  if (data.data?.access_token) return data.data;
-  throw new Error(`Token exchange failed: ${raw.slice(0, 200)}`);
-}
-
-async function run() {
-  // Start callback server to capture the code
-  let resolveCode;
-  const codePromise = new Promise(resolve => { resolveCode = resolve; });
-
-  const server = http.createServer((req, res) => {
-    const url = new URL(req.url, `http://127.0.0.1:${PORT}`);
-    if (url.pathname === '/callback') {
-      const code = url.searchParams.get('code');
-      res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
-      res.end(code ? '<h2>OK</h2>' : '<h2>No code</h2>');
-      if (code) resolveCode(code);
-    } else {
-      res.writeHead(404); res.end();
-    }
-  });
-  server.listen(PORT, '127.0.0.1');
-  console.log(`[server] Listening on port ${PORT}`);
-
-  // Launch browser — use the first page directly (no extra about:blank)
-  const browser = await chromium.launch({ headless: false });
-  const context = await browser.newContext({ viewport: { width: 1200, height: 800 } });
-  await context.addCookies(parseCookies(COOKIE_STR));
-
-  // Listen for any new page (popup) that might open
-  context.on('page', async newPage => {
-    const url = newPage.url();
-    console.log('[context] New page opened:', url.slice(0, 200));
-  });
-
-  // Get the default page instead of creating a new one
-  const pages = context.pages();
-  const page = pages.length > 0 ? pages[0] : await context.newPage();
-  page.setDefaultTimeout(30000);
-
-  try {
-    const authUrl = `https://accounts.feishu.cn/open-apis/authen/v1/authorize?client_id=${APP_ID}&redirect_uri=${encodeURIComponent(REDIRECT_URI)}&response_type=code&scope=${encodeURIComponent(SCOPES)}`;
-    console.log('\n[auth] Opening authorize URL...');
-
-    // Use route interception to capture the callback redirect directly
-    let codeFromRoute = null;
-    await context.route('**/callback**', async route => {
-      const url = route.request().url();
-      console.log('[route] Intercepted callback:', url.slice(0, 200));
-      const parsed = new URL(url);
-      const code = parsed.searchParams.get('code');
-      if (code) {
-        codeFromRoute = code;
-        resolveCode(code);
-      }
-      await route.continue();
-    });
-
-    await page.goto(authUrl, { waitUntil: 'load' });
-    await page.waitForTimeout(2000);
-
-    const currentUrl = page.url();
-    console.log('[auth] Current URL:', currentUrl.slice(0, 200));
-
-    if (currentUrl.includes('callback?code=')) {
-      console.log('[auth] Auto-authorized!');
-    } else {
-      // Find and click authorize button
-      const authorizeBtn = page.locator('button:has-text("授权")').first();
-      if (await authorizeBtn.isVisible().catch(() => false)) {
-        console.log('[auth] Found 授权 button, clicking...');
-        await authorizeBtn.click();
-        console.log('[auth] Clicked, waiting for redirect...');
-        await page.waitForTimeout(5000);
-        console.log('[auth] After click URL:', page.url().slice(0, 200));
-
-        // Check all pages in context
-        const allPages = context.pages();
-        console.log(`[auth] Total pages: ${allPages.length}`);
-        for (let i = 0; i < allPages.length; i++) {
-          const pUrl = allPages[i].url();
-          console.log(`  [${i}] ${pUrl.slice(0, 200)}`);
-          if (pUrl.includes('callback?code=')) {
-            const parsed = new URL(pUrl);
-            resolveCode(parsed.searchParams.get('code'));
-          }
-        }
-      } else {
-        console.log('[auth] No authorize button found!');
-        await page.screenshot({ path: '/tmp/feishu-oauth-nobutton.png' });
-      }
-    }
-
-    // Wait for the code
-    console.log('\n[token] Waiting for code...');
-    const code = await Promise.race([
-      codePromise,
-      new Promise((_, rej) => setTimeout(() => rej(new Error('Timeout (30s)')), 30000)),
-    ]);
-    console.log('[token] Got code:', code.slice(0, 20) + '...');
-
-    const tokenData = await exchangeCode(code);
-    saveToken(tokenData);
-    console.log('\n=== SUCCESS ===');
-    console.log('access_token:', tokenData.access_token?.slice(0, 30) + '...');
-    console.log('scope:', tokenData.scope);
-    console.log('expires_in:', tokenData.expires_in, 's');
-
-  } catch (e) {
-    console.error('\nError:', e.message);
-    await page.screenshot({ path: '/tmp/feishu-oauth-error.png' }).catch(() => {});
-  } finally {
-    await browser.close();
-    server.close();
-  }
-}
-
-run();