feishu-user-plugin 1.3.10 → 1.3.12

package/src/test-lark-desktop.js

@@ -0,0 +1,300 @@
+// src/test-lark-desktop.js — unit tests for src/auth/lark-desktop.js
+// + src/auth/credentials.js larkHash bindings.
+// Plain assert + fixture-based; no external deps.
+//
+// Run: `node src/test-lark-desktop.js`
+
+'use strict';
+
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const FIX_ROOT = path.join(os.tmpdir(), 'feishu-test-sdk-storage-' + process.pid + '-' + Date.now());
+
+function makeFixture(hashes) {
+  fs.mkdirSync(FIX_ROOT, { recursive: true });
+  for (const [hash, mtimeOffset] of hashes) {
+    const dir = path.join(FIX_ROOT, hash);
+    fs.mkdirSync(dir, { recursive: true });
+    const dbPath = path.join(dir, 'cookie_store.db');
+    fs.writeFileSync(dbPath, 'fake');
+    const t = (Date.now() / 1000) + mtimeOffset;
+    fs.utimesSync(dbPath, t, t);
+  }
+}
+
+function cleanupFixture() {
+  fs.rmSync(FIX_ROOT, { recursive: true, force: true });
+}
+
+const ld = require('./auth/lark-desktop');
+
+// --- Task 1: read-only basics ---
+
+function testListAccountHashes() {
+  cleanupFixture();
+  makeFixture([
+    ['aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa', -100],
+    ['bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb', 0],
+    ['cccccccccccccccccccccccccccccccc', -50],
+    ['notahash', 0],            // should be filtered out (not 32-hex)
+    ['DEADBEEFDEADBEEFDEADBEEFDEADBEEF', 0],   // uppercase — also filtered (we accept lowercase only)
+  ]);
+  // uppercase entry has no cookie_store.db tweaking — make sure dir exists at minimum
+  // (already created; just confirming file presence)
+  const list = ld.listAccountHashes({ dir: FIX_ROOT });
+  assert.strictEqual(list.length, 3, `filters non-hex names; got ${list.length}: ${list.map(h=>h.hash).join(',')}`);
+  assert.strictEqual(list[0].hash, 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb', 'sorted by mtime desc');
+  assert.strictEqual(list[2].hash, 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa');
+  assert.ok(typeof list[0].mtimeMs === 'number');
+  assert.ok(list[0].dir.endsWith('bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb'));
+  cleanupFixture();
+  console.log('PASS: listAccountHashes');
+}
+
+function testListAccountHashesEmpty() {
+  cleanupFixture();
+  fs.mkdirSync(FIX_ROOT, { recursive: true });
+  // No hash dirs — should return []
+  assert.deepStrictEqual(ld.listAccountHashes({ dir: FIX_ROOT }), []);
+  cleanupFixture();
+  // Non-existent dir
+  assert.deepStrictEqual(ld.listAccountHashes({ dir: '/nonexistent-' + Date.now() }), []);
+  console.log('PASS: listAccountHashes empty / missing');
+}
+
+function testListAccountHashesIgnoresMissingDb() {
+  cleanupFixture();
+  fs.mkdirSync(path.join(FIX_ROOT, 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'), { recursive: true });
+  // No cookie_store.db file inside — entry should be skipped (we treat
+  // "no DB → never logged in / cleared" so it can't represent an active account)
+  const list = ld.listAccountHashes({ dir: FIX_ROOT });
+  assert.strictEqual(list.length, 0);
+  cleanupFixture();
+  console.log('PASS: listAccountHashes ignores hash dirs without cookie_store.db');
+}
+
+function testMostRecentHash() {
+  cleanupFixture();
+  makeFixture([
+    ['1111111111111111111111111111aaaa', -200],
+    ['2222222222222222222222222222bbbb', 0],
+  ]);
+  const top = ld.mostRecentHash({ dir: FIX_ROOT });
+  assert.strictEqual(top.hash, '2222222222222222222222222222bbbb');
+  assert.strictEqual(ld.mostRecentHash({ dir: '/nonexistent-' + Date.now() }), null);
+  cleanupFixture();
+  console.log('PASS: mostRecentHash');
+}
+
+function testGetSdkStorageDirSafety() {
+  const dir = ld.getSdkStorageDir();
+  if (process.platform === 'darwin') {
+    assert.ok(dir === null || typeof dir === 'string');
+  } else {
+    assert.strictEqual(dir, null);
+  }
+  console.log('PASS: getSdkStorageDir platform safety');
+}
+
+// --- Task 2: profile hash bindings on credentials.js ---
+
+function testProfileHashBindings() {
+  const sandbox = path.join(os.tmpdir(), 'feishu-test-creds-' + process.pid + '-' + Date.now());
+  fs.mkdirSync(path.join(sandbox, '.feishu-user-plugin'), { recursive: true, mode: 0o700 });
+  const credPath = path.join(sandbox, '.feishu-user-plugin', 'credentials.json');
+
+  const baseFile = {
+    version: 1,
+    active: 'default',
+    profiles: {
+      default: { LARK_APP_ID: 'cli_aaa' },
+      work: { LARK_APP_ID: 'cli_bbb' },
+    },
+    profileHints: {},
+  };
+  fs.writeFileSync(credPath, JSON.stringify(baseFile, null, 2));
+
+  const origHome = process.env.HOME;
+  process.env.HOME = sandbox;
+
+  // Force re-require so any cached internal state in credentials.js is fresh.
+  // (credentials.js doesn't actually cache — it re-reads on every call — but
+  // belt-and-suspenders.)
+  delete require.cache[require.resolve('./auth/credentials')];
+  const credentials = require('./auth/credentials');
+
+  try {
+    // Initially unbound
+    assert.strictEqual(credentials.findProfileByHash('aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'), null);
+    assert.strictEqual(credentials.getProfileLarkHash('default'), null);
+    assert.strictEqual(credentials.getProfileLarkHash('work'), null);
+
+    // Bind default
+    credentials.setProfileLarkHash('default', 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa');
+    assert.strictEqual(credentials.getProfileLarkHash('default'), 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa');
+    assert.strictEqual(credentials.findProfileByHash('aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'), 'default');
+
+    // Bind work
+    credentials.setProfileLarkHash('work', 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb');
+    assert.strictEqual(credentials.findProfileByHash('bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb'), 'work');
+    // default still bound
+    assert.strictEqual(credentials.findProfileByHash('aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'), 'default');
+
+    // Validation: bad hex
+    assert.throws(() => credentials.setProfileLarkHash('default', 'not-hex'),
+      /must be 32-char hex/);
+    // Validation: missing profile
+    assert.throws(() => credentials.setProfileLarkHash('nope', 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'),
+      /not found/);
+
+    // findProfileByHash with bad input → null
+    assert.strictEqual(credentials.findProfileByHash('not-hex'), null);
+    assert.strictEqual(credentials.findProfileByHash(null), null);
+    assert.strictEqual(credentials.findProfileByHash(undefined), null);
+
+    // Clear by passing null
+    credentials.setProfileLarkHash('default', null);
+    assert.strictEqual(credentials.getProfileLarkHash('default'), null);
+    assert.strictEqual(credentials.findProfileByHash('aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'), null);
+  } finally {
+    process.env.HOME = origHome;
+    fs.rmSync(sandbox, { recursive: true, force: true });
+    delete require.cache[require.resolve('./auth/credentials')];
+  }
+  console.log('PASS: profile hash bindings');
+}
+
+// --- Task 4: detectSwitch logic (pure) ---
+
+function testDetectSwitchDebounce() {
+  const result = ld.detectSwitch({
+    prevSnapshot: {},
+    lastSwitchAt: Date.now() - 1000,        // 1s ago, < 5s debounce
+    seenUnboundHashes: new Set(),
+    listFn: () => [{ hash: 'a'.repeat(32), mtimeMs: Date.now(), dir: '/x' }],
+    credsApi: { getActiveProfileName: () => 'default', getProfileLarkHash: () => null, findProfileByHash: () => 'default' },
+  });
+  assert.deepStrictEqual(result, { switchTo: null, isUnbound: false });
+  console.log('PASS: detectSwitch debounce');
+}
+
+function testDetectSwitchAlreadyOnMostRecent() {
+  const HASH = 'a'.repeat(32);
+  const result = ld.detectSwitch({
+    prevSnapshot: {},
+    lastSwitchAt: 0,
+    seenUnboundHashes: new Set(),
+    listFn: () => [{ hash: HASH, mtimeMs: Date.now(), dir: '/x' }],
+    credsApi: { getActiveProfileName: () => 'default', getProfileLarkHash: () => HASH, findProfileByHash: () => 'default' },
+  });
+  assert.deepStrictEqual(result, { switchTo: null, isUnbound: false });
+  console.log('PASS: detectSwitch already on most-recent');
+}
+
+function testDetectSwitchNoMtimeAdvance() {
+  const HASH = 'a'.repeat(32);
+  const fixedMtime = Date.now() - 10_000;
+  const result = ld.detectSwitch({
+    prevSnapshot: { [HASH]: fixedMtime },
+    lastSwitchAt: 0,
+    seenUnboundHashes: new Set(),
+    listFn: () => [{ hash: HASH, mtimeMs: fixedMtime, dir: '/x' }],
+    credsApi: { getActiveProfileName: () => 'default', getProfileLarkHash: () => 'b'.repeat(32), findProfileByHash: () => 'work' },
+  });
+  assert.deepStrictEqual(result, { switchTo: null, isUnbound: false });
+  console.log('PASS: detectSwitch no mtime advance');
+}
+
+function testDetectSwitchValid() {
+  const HASH = 'a'.repeat(32);
+  const result = ld.detectSwitch({
+    prevSnapshot: { [HASH]: 1000 },
+    lastSwitchAt: 0,
+    seenUnboundHashes: new Set(),
+    listFn: () => [{ hash: HASH, mtimeMs: 5000, dir: '/x' }],
+    credsApi: { getActiveProfileName: () => 'default', getProfileLarkHash: () => 'b'.repeat(32), findProfileByHash: () => 'work' },
+  });
+  assert.deepStrictEqual(result, { switchTo: { hash: HASH, profile: 'work' }, isUnbound: false });
+  console.log('PASS: detectSwitch valid switch');
+}
+
+function testDetectSwitchUnboundEmitsOnce() {
+  const HASH = 'a'.repeat(32);
+  const seen = new Set();
+  const logs = [];
+  const log = (msg) => logs.push(msg);
+  const args = {
+    prevSnapshot: { [HASH]: 1000 },
+    lastSwitchAt: 0,
+    seenUnboundHashes: seen,
+    listFn: () => [{ hash: HASH, mtimeMs: Date.now(), dir: '/x' }],
+    credsApi: { getActiveProfileName: () => 'default', getProfileLarkHash: () => null, findProfileByHash: () => null },
+    log,
+  };
+  let r = ld.detectSwitch(args);
+  assert.deepStrictEqual(r, { switchTo: null, isUnbound: true, hash: HASH });
+  assert.strictEqual(logs.length, 1, 'first call emits hint');
+  assert.match(logs[0], /not bound to any MCP profile/);
+  assert.match(logs[0], new RegExp(`--bind-hash ${HASH}`));
+  r = ld.detectSwitch(args);
+  assert.strictEqual(logs.length, 1, 'second call deduplicated');
+  console.log('PASS: detectSwitch unbound emits hint once per session');
+}
+
+function testDetectSwitchUnboundStaleNoHint() {
+  // mtime older than UNBOUND_FRESH_WINDOW_MS → no hint emitted
+  const HASH = 'a'.repeat(32);
+  const seen = new Set();
+  const logs = [];
+  const r = ld.detectSwitch({
+    prevSnapshot: { [HASH]: 1000 },
+    lastSwitchAt: 0,
+    seenUnboundHashes: seen,
+    listFn: () => [{ hash: HASH, mtimeMs: Date.now() - 120_000, dir: '/x' }],   // 2 min ago
+    credsApi: { getActiveProfileName: () => 'default', getProfileLarkHash: () => null, findProfileByHash: () => null },
+    log: (msg) => logs.push(msg),
+  });
+  // Stale unbound hash: still reports isUnbound=true but doesn't add to seen / doesn't log
+  assert.strictEqual(r.isUnbound, true);
+  assert.strictEqual(logs.length, 0);
+  assert.strictEqual(seen.size, 0);
+  console.log('PASS: detectSwitch unbound stale → no hint');
+}
+
+function testDetectSwitchEmptyList() {
+  const r = ld.detectSwitch({
+    prevSnapshot: {},
+    lastSwitchAt: 0,
+    seenUnboundHashes: new Set(),
+    listFn: () => [],
+    credsApi: { getActiveProfileName: () => 'default', getProfileLarkHash: () => null, findProfileByHash: () => null },
+  });
+  assert.deepStrictEqual(r, { switchTo: null, isUnbound: false });
+  console.log('PASS: detectSwitch empty list');
+}
+
+// --- Run all ---
+
+function run() {
+  testListAccountHashes();
+  testListAccountHashesEmpty();
+  testListAccountHashesIgnoresMissingDb();
+  testMostRecentHash();
+  testGetSdkStorageDirSafety();
+  testProfileHashBindings();
+  testDetectSwitchDebounce();
+  testDetectSwitchAlreadyOnMostRecent();
+  testDetectSwitchNoMtimeAdvance();
+  testDetectSwitchValid();
+  testDetectSwitchUnboundEmitsOnce();
+  testDetectSwitchUnboundStaleNoHint();
+  testDetectSwitchEmptyList();
+  console.log('\nAll lark-desktop tests passed.');
+}
+
+if (require.main === module) {
+  run();
+}

package/src/test-lockfile-pid.js

@@ -0,0 +1,90 @@
+// src/test-lockfile-pid.js — verify acquireLongLived's v1.3.12 PID
+// liveness check.
+//
+// Pre-v1.3.12 the lock was judged "alive" purely by mtime: heartbeat every
+// 15s, stale after 60s. If the owner process got SIGKILL'd (or crashed
+// mid-heartbeat), the lock looked alive for up to 60s. With the WS event
+// subscription tied to the lock, a hung owner blocked event ingestion for
+// the entire window.
+//
+// New behaviour: when stat says mtime is fresh, ALSO read the lock body and
+// `process.kill(pid, 0)`. If ESRCH → process is gone, lock is steal-eligible
+// immediately regardless of mtime.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const assert = require('node:assert/strict');
+const { acquireLongLived } = require('./events/lockfile');
+
+function run() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'fish-pid-lock-'));
+  const lockPath = path.join(dir, 'test.lock');
+
+  // --- 1. Write a lock body for a pid that definitely doesn't exist.
+  //        PID 1 is init/launchd — always exists; we need a pid that's
+  //        certainly gone. Use a huge integer well outside the kernel's
+  //        normal range; the most portable check is process.kill(pid, 0).
+  const fakePid = 999_999_999;
+  const body = JSON.stringify({ version: 1, pid: fakePid, start_time: Math.floor(Date.now() / 1000), role: 'test_dead_owner' });
+  fs.writeFileSync(lockPath, body, { mode: 0o600 });
+  // Fresh mtime — pre-v1.3.12 this would block acquisition for 60s.
+  fs.utimesSync(lockPath, new Date(), new Date());
+
+  const handle = acquireLongLived(lockPath, { info: { role: 'new_owner' }, staleMs: 60_000 });
+  assert.ok(handle, 'should be able to steal lock when holder pid is dead, even when mtime is fresh');
+
+  // Read body — should now contain THIS process's pid.
+  const newBody = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
+  assert.equal(newBody.pid, process.pid);
+
+  handle.release();
+
+  // --- 2. Live pid (this process) prevents acquisition even past staleMs
+  //        when content shows we're still alive — but for safety we treat
+  //        EPERM (different user, can't probe) as alive too. Skip EPERM
+  //        case since it requires multi-user setup.
+  const livePid = process.pid;
+  const liveBody = JSON.stringify({ version: 1, pid: livePid, start_time: Math.floor(Date.now() / 1000), role: 'live_owner' });
+  fs.writeFileSync(lockPath, liveBody, { mode: 0o600 });
+  fs.utimesSync(lockPath, new Date(), new Date());
+  const blocked = acquireLongLived(lockPath, { info: {}, staleMs: 60_000 });
+  assert.equal(blocked, null, 'live pid + fresh mtime → cannot steal');
+  fs.unlinkSync(lockPath); // cleanup
+
+  // --- 3. Stale mtime + live pid: previously would have stolen; new behaviour
+  //        keeps the steal because mtime says heartbeat is dead.
+  //        (We don't try to second-guess a stuck process — mtime is the
+  //        primary signal; PID check only adds the ability to reclaim
+  //        FASTER when process is definitively dead.)
+  fs.writeFileSync(lockPath, JSON.stringify({ version: 1, pid: livePid, start_time: Math.floor(Date.now() / 1000) - 999 }), { mode: 0o600 });
+  // Backdate mtime well past staleMs.
+  const backdate = new Date(Date.now() - 120_000);
+  fs.utimesSync(lockPath, backdate, backdate);
+  const stolenLive = acquireLongLived(lockPath, { info: {}, staleMs: 60_000 });
+  assert.ok(stolenLive, 'stale mtime should still allow takeover (back-compat)');
+  stolenLive.release();
+
+  // --- 4. Body missing pid field (legacy locks from older versions) — fall
+  //        back to mtime-only check (existing behaviour, no regression).
+  fs.writeFileSync(lockPath, JSON.stringify({ version: 1 }), { mode: 0o600 });
+  fs.utimesSync(lockPath, new Date(), new Date());
+  const noPidBlocked = acquireLongLived(lockPath, { info: {}, staleMs: 60_000 });
+  assert.equal(noPidBlocked, null, 'no pid in body → fall back to mtime, fresh mtime blocks');
+  fs.unlinkSync(lockPath);
+
+  // --- 5. Malformed lock body (not JSON) — mtime-only fallback.
+  fs.writeFileSync(lockPath, 'not json at all', { mode: 0o600 });
+  fs.utimesSync(lockPath, new Date(), new Date());
+  const malformedBlocked = acquireLongLived(lockPath, { info: {}, staleMs: 60_000 });
+  assert.equal(malformedBlocked, null, 'malformed body → fall back to mtime, fresh mtime blocks');
+  fs.unlinkSync(lockPath);
+
+  fs.rmSync(dir, { recursive: true, force: true });
+  console.log('lockfile-pid.js: PASS');
+}
+
+if (require.main === module) run();
+module.exports = { run };

package/src/test-lru-cache.js

@@ -0,0 +1,145 @@
+// src/test-lru-cache.js — unit test for src/utils/lru-cache.js.
+//
+// Replaces the v1.3.12 `new Map()` _userNameCache / _appNameCache. Pre-fix the
+// caches grew unboundedly across the server's lifetime (one entry per unique
+// open_id ever seen) and never expired — a 1-week-uptime MCP would carry
+// stale display names from messages of users who renamed themselves days ago.
+//
+// LRU with TTL solves both:
+//   - max=500 caps the per-process memory at O(KiB) regardless of message volume
+//   - ttlMs=10min ensures rename / leave-tenant changes get re-resolved
+//
+// We test the basic operations + interactions between TTL and LRU.
+
+'use strict';
+
+const assert = require('node:assert/strict');
+const { LRUCache } = require('./utils');
+
+async function run() {
+  // --- 1. set/get/has roundtrip ---
+  {
+    const c = new LRUCache({ max: 5, ttlMs: 1000 });
+    c.set('a', 1);
+    assert.equal(c.get('a'), 1);
+    assert.equal(c.has('a'), true);
+    assert.equal(c.get('missing'), undefined);
+    assert.equal(c.has('missing'), false);
+    assert.equal(c.size, 1);
+  }
+
+  // --- 2. LRU eviction: oldest dropped when over max ---
+  {
+    const c = new LRUCache({ max: 3, ttlMs: 60_000 });
+    c.set('a', 1);
+    c.set('b', 2);
+    c.set('c', 3);
+    c.set('d', 4); // evicts 'a'
+    assert.equal(c.has('a'), false);
+    assert.equal(c.get('b'), 2);
+    assert.equal(c.get('c'), 3);
+    assert.equal(c.get('d'), 4);
+    assert.equal(c.size, 3);
+  }
+
+  // --- 3. Access promotes recency: get prevents eviction ---
+  {
+    const c = new LRUCache({ max: 3, ttlMs: 60_000 });
+    c.set('a', 1);
+    c.set('b', 2);
+    c.set('c', 3);
+    c.get('a'); // 'a' becomes most-recently-used; 'b' is now LRU
+    c.set('d', 4); // evicts 'b'
+    assert.equal(c.has('a'), true);
+    assert.equal(c.has('b'), false);
+    assert.equal(c.has('c'), true);
+    assert.equal(c.has('d'), true);
+  }
+
+  // --- 4. TTL expiry: get returns undefined for expired ---
+  {
+    const c = new LRUCache({ max: 10, ttlMs: 50 });
+    c.set('a', 1);
+    assert.equal(c.get('a'), 1);
+    await new Promise(r => setTimeout(r, 80));
+    assert.equal(c.get('a'), undefined, 'expired entries return undefined');
+    assert.equal(c.has('a'), false);
+    // Expired entry is purged: size drops.
+    assert.equal(c.size, 0);
+  }
+
+  // --- 5. Setting an existing key refreshes TTL ---
+  {
+    const c = new LRUCache({ max: 10, ttlMs: 100 });
+    c.set('a', 1);
+    await new Promise(r => setTimeout(r, 60));
+    c.set('a', 1); // refresh
+    await new Promise(r => setTimeout(r, 60));
+    // 120ms total since first set, only 60ms since refresh — still valid.
+    assert.equal(c.get('a'), 1);
+  }
+
+  // --- 6. delete + clear ---
+  {
+    const c = new LRUCache({ max: 5, ttlMs: 1000 });
+    c.set('a', 1);
+    c.set('b', 2);
+    c.delete('a');
+    assert.equal(c.has('a'), false);
+    assert.equal(c.size, 1);
+    c.clear();
+    assert.equal(c.size, 0);
+    assert.equal(c.has('b'), false);
+  }
+
+  // --- 7. Map-compatible shim (we replace `new Map()` in base.js — the
+  // existing call sites use .has / .get / .set / .clear, which the class
+  // implements identically. Smoke-check parity here.) ---
+  {
+    const c = new LRUCache({ max: 5, ttlMs: 1000 });
+    c.set('open_x', 'Alice');
+    assert.equal(c.has('open_x'), true);
+    assert.equal(c.get('open_x'), 'Alice');
+  }
+
+  // --- 8. Iteration support: the comment claims "API-compatible with the
+  // old Map", so spread / for-of / entries / keys / values must all work.
+  // Map is iterable via Symbol.iterator yielding [key, value] tuples.
+  {
+    const c = new LRUCache({ max: 5, ttlMs: 60_000 });
+    c.set('a', 1);
+    c.set('b', 2);
+    c.set('c', 3);
+    const collected = [...c];
+    assert.equal(collected.length, 3);
+    // Map insertion order, [key, value] tuples.
+    assert.deepEqual(collected[0], ['a', 1]);
+    assert.deepEqual(collected[2], ['c', 3]);
+
+    const forOfKeys = [];
+    for (const [k] of c) forOfKeys.push(k);
+    assert.deepEqual(forOfKeys, ['a', 'b', 'c']);
+
+    assert.deepEqual([...c.keys()], ['a', 'b', 'c']);
+    assert.deepEqual([...c.values()], [1, 2, 3]);
+    assert.deepEqual([...c.entries()], [['a', 1], ['b', 2], ['c', 3]]);
+  }
+
+  // --- 9. Iteration skips expired entries (TTL gate is consistent across
+  // get/has and iteration so callers don't see stale data via spread).
+  {
+    const c = new LRUCache({ max: 5, ttlMs: 50 });
+    c.set('a', 1);
+    c.set('b', 2);
+    await new Promise(r => setTimeout(r, 80));
+    c.set('c', 3); // fresh after expiry of a/b
+    const collected = [...c];
+    assert.equal(collected.length, 1);
+    assert.deepEqual(collected[0], ['c', 3]);
+  }
+
+  console.log('lru-cache.js: PASS');
+}
+
+if (require.main === module) run().catch(e => { console.error(e); process.exit(1); });
+module.exports = { run };

package/src/test-negative-cache.js

@@ -0,0 +1,85 @@
+// src/test-negative-cache.js — verify _populateSenderNames writes a null
+// sentinel for un-resolvable open_ids so repeated read_messages calls
+// don't re-fire the same contact API request.
+//
+// Pre-fix bug: contacts.js::getUserById returned null on failure without
+// writing to _userNameCache, so every subsequent _populateSenderNames
+// invocation re-added the same id to unknownUserIds and dispatched another
+// API call. In a hot chat with N un-resolvable senders that's N redundant
+// API calls per read_messages — observed in the 2026-05 incident's stderr.
+//
+// Fix lives in _populateSenderNames itself (not in contacts.js): after each
+// Promise.allSettled batch, ids still absent from _userNameCache get a null
+// sentinel written. has(id)==true / get(id)==null on next call → the loop
+// skips the id entirely, _computeDisplayLabel falls back to "(open_id)"
+// the same way it would have without a cache.
+
+'use strict';
+
+const assert = require('node:assert/strict');
+const { LarkOfficialClient } = require('./clients/official');
+
+async function run() {
+  const c = new LarkOfficialClient('cli_test', 'fake_secret');
+  // Stub self tenant probe so the real one doesn't hit Feishu.
+  c._resolveSelfTenantKey = async () => 'tenant_self';
+  c._selfTenantKey = 'tenant_self';
+
+  // Mock getUserById to simulate a un-resolvable user: cache nothing,
+  // return null. The fix in _populateSenderNames is what should write the
+  // null sentinel afterwards.
+  let userCallCount = 0;
+  c.getUserById = async (userId) => {
+    if (c._userNameCache.has(userId)) return c._userNameCache.get(userId);
+    userCallCount++;
+    return null;
+  };
+
+  // Same for getAppName.
+  let appCallCount = 0;
+  c.getAppName = async (appId) => {
+    if (c._appNameCache.has(appId)) return c._appNameCache.get(appId);
+    appCallCount++;
+    return null;
+  };
+
+  // --- 1. User negative-cache: un-resolvable ou_bad ---
+  const items1 = [{ senderId: 'ou_bad', senderType: 'user' }];
+  await c._populateSenderNames(items1, null);
+  assert.equal(userCallCount, 1, 'first populate dispatches one API call');
+  assert.equal(items1[0].senderName, null);
+  assert.equal(items1[0].displayLabel, '(ou_bad)');
+
+  // Cache must now hold a null sentinel.
+  assert.equal(c._userNameCache.has('ou_bad'), true, 'null sentinel written for un-resolvable id');
+  assert.equal(c._userNameCache.get('ou_bad'), null);
+
+  // --- 2. Same id, second populate → cache hit, no new API call ---
+  const items2 = [{ senderId: 'ou_bad', senderType: 'user' }];
+  await c._populateSenderNames(items2, null);
+  assert.equal(userCallCount, 1, 'cached null skips dispatch');
+  assert.equal(items2[0].displayLabel, '(ou_bad)');
+
+  // --- 3. Mixed batch: new id triggers exactly one new call ---
+  const items3 = [
+    { senderId: 'ou_bad', senderType: 'user' },
+    { senderId: 'ou_new', senderType: 'user' },
+  ];
+  await c._populateSenderNames(items3, null);
+  assert.equal(userCallCount, 2, 'new id alone dispatches one new call');
+
+  // --- 4. App negative-cache: un-resolvable cli_bad ---
+  const items4 = [{ senderId: 'cli_bad', senderType: 'app' }];
+  await c._populateSenderNames(items4, null);
+  assert.equal(appCallCount, 1);
+  assert.equal(items4[0].displayLabel, '[Bot] (cli_bad)');
+
+  const items5 = [{ senderId: 'cli_bad', senderType: 'app' }];
+  await c._populateSenderNames(items5, null);
+  assert.equal(appCallCount, 1, 'cached null app skips dispatch');
+
+  console.log('negative-cache.js: PASS');
+}
+
+if (require.main === module) run().catch(e => { console.error(e); process.exit(1); });
+module.exports = { run };