@openclaw/feishu 2026.2.21 → 2026.2.23

package/src/dedup.ts

@@ -1,33 +1,54 @@
-// Prevent duplicate processing when WebSocket reconnects or Feishu redelivers messages.
-const DEDUP_TTL_MS = 30 * 60 * 1000; // 30 minutes
-const DEDUP_MAX_SIZE = 1_000;
-const DEDUP_CLEANUP_INTERVAL_MS = 5 * 60 * 1000; // cleanup every 5 minutes
-const processedMessageIds = new Map<string, number>(); // messageId -> timestamp
-let lastCleanupTime = Date.now();
+import os from "node:os";
+import path from "node:path";
+import { createDedupeCache, createPersistentDedupe } from "openclaw/plugin-sdk";
 
-export function tryRecordMessage(messageId: string): boolean {
-  const now = Date.now();
+// Persistent TTL: 24 hours — survives restarts & WebSocket reconnects.
+const DEDUP_TTL_MS = 24 * 60 * 60 * 1000;
+const MEMORY_MAX_SIZE = 1_000;
+const FILE_MAX_ENTRIES = 10_000;
 
-  // Throttled cleanup: evict expired entries at most once per interval.
-  if (now - lastCleanupTime > DEDUP_CLEANUP_INTERVAL_MS) {
-    for (const [id, ts] of processedMessageIds) {
-      if (now - ts > DEDUP_TTL_MS) {
-        processedMessageIds.delete(id);
-      }
-    }
-    lastCleanupTime = now;
-  }
+const memoryDedupe = createDedupeCache({ ttlMs: DEDUP_TTL_MS, maxSize: MEMORY_MAX_SIZE });
 
-  if (processedMessageIds.has(messageId)) {
-    return false;
+function resolveStateDirFromEnv(env: NodeJS.ProcessEnv = process.env): string {
+  const stateOverride = env.OPENCLAW_STATE_DIR?.trim() || env.CLAWDBOT_STATE_DIR?.trim();
+  if (stateOverride) {
+    return stateOverride;
   }
-
-  // Evict oldest entries if cache is full.
-  if (processedMessageIds.size >= DEDUP_MAX_SIZE) {
-    const first = processedMessageIds.keys().next().value!;
-    processedMessageIds.delete(first);
+  if (env.VITEST || env.NODE_ENV === "test") {
+    return path.join(os.tmpdir(), ["openclaw-vitest", String(process.pid)].join("-"));
   }
+  return path.join(os.homedir(), ".openclaw");
+}
+
+function resolveNamespaceFilePath(namespace: string): string {
+  const safe = namespace.replace(/[^a-zA-Z0-9_-]/g, "_");
+  return path.join(resolveStateDirFromEnv(), "feishu", "dedup", `${safe}.json`);
+}
+
+const persistentDedupe = createPersistentDedupe({
+  ttlMs: DEDUP_TTL_MS,
+  memoryMaxSize: MEMORY_MAX_SIZE,
+  fileMaxEntries: FILE_MAX_ENTRIES,
+  resolveFilePath: resolveNamespaceFilePath,
+});
+
+/**
+ * Synchronous dedup — memory only.
+ * Kept for backward compatibility; prefer {@link tryRecordMessagePersistent}.
+ */
+export function tryRecordMessage(messageId: string): boolean {
+  return !memoryDedupe.check(messageId);
+}
 
-  processedMessageIds.set(messageId, now);
-  return true;
+export async function tryRecordMessagePersistent(
+  messageId: string,
+  namespace = "global",
+  log?: (...args: unknown[]) => void,
+): Promise<boolean> {
+  return persistentDedupe.checkAndRecord(messageId, {
+    namespace,
+    onDiskError: (error) => {
+      log?.(`feishu-dedup: disk error, falling back to memory: ${String(error)}`);
+    },
+  });
 }

package/src/media.test.ts

@@ -38,6 +38,16 @@ vi.mock("./runtime.js", () => ({
 
 import { downloadImageFeishu, downloadMessageResourceFeishu, sendMediaFeishu } from "./media.js";
 
+function expectPathIsolatedToTmpRoot(pathValue: string, key: string): void {
+  expect(pathValue).not.toContain(key);
+  expect(pathValue).not.toContain("..");
+
+  const tmpRoot = path.resolve(os.tmpdir());
+  const resolved = path.resolve(pathValue);
+  const rel = path.relative(tmpRoot, resolved);
+  expect(rel === ".." || rel.startsWith(`..${path.sep}`)).toBe(false);
+}
+
 describe("sendMediaFeishu msg_type routing", () => {
   beforeEach(() => {
     vi.clearAllMocks();
@@ -217,13 +227,7 @@ describe("sendMediaFeishu msg_type routing", () => {
 
     expect(result.buffer).toEqual(Buffer.from("image-data"));
     expect(capturedPath).toBeDefined();
-    expect(capturedPath).not.toContain(imageKey);
-    expect(capturedPath).not.toContain("..");
-
-    const tmpRoot = path.resolve(os.tmpdir());
-    const resolved = path.resolve(capturedPath as string);
-    const rel = path.relative(tmpRoot, resolved);
-    expect(rel === ".." || rel.startsWith(`..${path.sep}`)).toBe(false);
+    expectPathIsolatedToTmpRoot(capturedPath as string, imageKey);
   });
 
   it("uses isolated temp paths for message resource downloads", async () => {
@@ -246,13 +250,7 @@ describe("sendMediaFeishu msg_type routing", () => {
 
     expect(result.buffer).toEqual(Buffer.from("resource-data"));
     expect(capturedPath).toBeDefined();
-    expect(capturedPath).not.toContain(fileKey);
-    expect(capturedPath).not.toContain("..");
-
-    const tmpRoot = path.resolve(os.tmpdir());
-    const resolved = path.resolve(capturedPath as string);
-    const rel = path.relative(tmpRoot, resolved);
-    expect(rel === ".." || rel.startsWith(`..${path.sep}`)).toBe(false);
+    expectPathIsolatedToTmpRoot(capturedPath as string, fileKey);
   });
 
   it("rejects invalid image keys before calling feishu api", async () => {

package/src/media.ts

@@ -7,7 +7,7 @@ import { createFeishuClient } from "./client.js";
 import { normalizeFeishuExternalKey } from "./external-keys.js";
 import { getFeishuRuntime } from "./runtime.js";
 import { assertFeishuMessageApiSuccess, toFeishuSendResult } from "./send-result.js";
-import { resolveReceiveIdType, normalizeFeishuTarget } from "./targets.js";
+import { resolveFeishuSendTarget } from "./send-target.js";
 
 export type DownloadImageResult = {
   buffer: Buffer;
@@ -268,18 +268,11 @@ export async function sendImageFeishu(params: {
   accountId?: string;
 }): Promise<SendMediaResult> {
   const { cfg, to, imageKey, replyToMessageId, accountId } = params;
-  const account = resolveFeishuAccount({ cfg, accountId });
-  if (!account.configured) {
-    throw new Error(`Feishu account "${account.accountId}" not configured`);
-  }
-
-  const client = createFeishuClient(account);
-  const receiveId = normalizeFeishuTarget(to);
-  if (!receiveId) {
-    throw new Error(`Invalid Feishu target: ${to}`);
-  }
-
-  const receiveIdType = resolveReceiveIdType(receiveId);
+  const { client, receiveId, receiveIdType } = resolveFeishuSendTarget({
+    cfg,
+    to,
+    accountId,
+  });
   const content = JSON.stringify({ image_key: imageKey });
 
   if (replyToMessageId) {
@@ -320,18 +313,11 @@ export async function sendFileFeishu(params: {
 }): Promise<SendMediaResult> {
   const { cfg, to, fileKey, replyToMessageId, accountId } = params;
   const msgType = params.msgType ?? "file";
-  const account = resolveFeishuAccount({ cfg, accountId });
-  if (!account.configured) {
-    throw new Error(`Feishu account "${account.accountId}" not configured`);
-  }
-
-  const client = createFeishuClient(account);
-  const receiveId = normalizeFeishuTarget(to);
-  if (!receiveId) {
-    throw new Error(`Invalid Feishu target: ${to}`);
-  }
-
-  const receiveIdType = resolveReceiveIdType(receiveId);
+  const { client, receiveId, receiveIdType } = resolveFeishuSendTarget({
+    cfg,
+    to,
+    accountId,
+  });
   const content = JSON.stringify({ file_key: fileKey });
 
   if (replyToMessageId) {

package/src/monitor.webhook-security.test.ts

@@ -78,6 +78,41 @@ function buildConfig(params: {
   } as ClawdbotConfig;
 }
 
+async function withRunningWebhookMonitor(
+  params: {
+    accountId: string;
+    path: string;
+    verificationToken: string;
+  },
+  run: (url: string) => Promise<void>,
+) {
+  const port = await getFreePort();
+  const cfg = buildConfig({
+    accountId: params.accountId,
+    path: params.path,
+    port,
+    verificationToken: params.verificationToken,
+  });
+
+  const abortController = new AbortController();
+  const runtime = { log: vi.fn(), error: vi.fn(), exit: vi.fn() };
+  const monitorPromise = monitorFeishuProvider({
+    config: cfg,
+    runtime,
+    abortSignal: abortController.signal,
+  });
+
+  const url = `http://127.0.0.1:${port}${params.path}`;
+  await waitUntilServerReady(url);
+
+  try {
+    await run(url);
+  } finally {
+    abortController.abort();
+    await monitorPromise;
+  }
+}
+
 afterEach(() => {
   stopFeishuMonitor();
 });
@@ -99,76 +134,50 @@ describe("Feishu webhook security hardening", () => {
 
   it("returns 415 for POST requests without json content type", async () => {
     probeFeishuMock.mockResolvedValue({ ok: true, botOpenId: "bot_open_id" });
-    const port = await getFreePort();
-    const path = "/hook-content-type";
-    const cfg = buildConfig({
-      accountId: "content-type",
-      path,
-      port,
-      verificationToken: "verify_token",
-    });
-
-    const abortController = new AbortController();
-    const runtime = { log: vi.fn(), error: vi.fn(), exit: vi.fn() };
-    const monitorPromise = monitorFeishuProvider({
-      config: cfg,
-      runtime,
-      abortSignal: abortController.signal,
-    });
-
-    await waitUntilServerReady(`http://127.0.0.1:${port}${path}`);
-
-    const response = await fetch(`http://127.0.0.1:${port}${path}`, {
-      method: "POST",
-      headers: { "content-type": "text/plain" },
-      body: "{}",
-    });
-
-    expect(response.status).toBe(415);
-    expect(await response.text()).toBe("Unsupported Media Type");
-
-    abortController.abort();
-    await monitorPromise;
+    await withRunningWebhookMonitor(
+      {
+        accountId: "content-type",
+        path: "/hook-content-type",
+        verificationToken: "verify_token",
+      },
+      async (url) => {
+        const response = await fetch(url, {
+          method: "POST",
+          headers: { "content-type": "text/plain" },
+          body: "{}",
+        });
+
+        expect(response.status).toBe(415);
+        expect(await response.text()).toBe("Unsupported Media Type");
+      },
+    );
   });
 
   it("rate limits webhook burst traffic with 429", async () => {
     probeFeishuMock.mockResolvedValue({ ok: true, botOpenId: "bot_open_id" });
-    const port = await getFreePort();
-    const path = "/hook-rate-limit";
-    const cfg = buildConfig({
-      accountId: "rate-limit",
-      path,
-      port,
-      verificationToken: "verify_token",
-    });
-
-    const abortController = new AbortController();
-    const runtime = { log: vi.fn(), error: vi.fn(), exit: vi.fn() };
-    const monitorPromise = monitorFeishuProvider({
-      config: cfg,
-      runtime,
-      abortSignal: abortController.signal,
-    });
-
-    await waitUntilServerReady(`http://127.0.0.1:${port}${path}`);
-
-    let saw429 = false;
-    for (let i = 0; i < 130; i += 1) {
-      const response = await fetch(`http://127.0.0.1:${port}${path}`, {
-        method: "POST",
-        headers: { "content-type": "text/plain" },
-        body: "{}",
-      });
-      if (response.status === 429) {
-        saw429 = true;
-        expect(await response.text()).toBe("Too Many Requests");
-        break;
-      }
-    }
-
-    expect(saw429).toBe(true);
-
-    abortController.abort();
-    await monitorPromise;
+    await withRunningWebhookMonitor(
+      {
+        accountId: "rate-limit",
+        path: "/hook-rate-limit",
+        verificationToken: "verify_token",
+      },
+      async (url) => {
+        let saw429 = false;
+        for (let i = 0; i < 130; i += 1) {
+          const response = await fetch(url, {
+            method: "POST",
+            headers: { "content-type": "text/plain" },
+            body: "{}",
+          });
+          if (response.status === 429) {
+            saw429 = true;
+            expect(await response.text()).toBe("Too Many Requests");
+            break;
+          }
+        }
+
+        expect(saw429).toBe(true);
+      },
+    );
   });
 });

package/src/onboarding.ts

@@ -104,6 +104,25 @@ async function noteFeishuCredentialHelp(prompter: WizardPrompter): Promise<void>
   );
 }
 
+async function promptFeishuCredentials(prompter: WizardPrompter): Promise<{
+  appId: string;
+  appSecret: string;
+}> {
+  const appId = String(
+    await prompter.text({
+      message: "Enter Feishu App ID",
+      validate: (value) => (value?.trim() ? undefined : "Required"),
+    }),
+  ).trim();
+  const appSecret = String(
+    await prompter.text({
+      message: "Enter Feishu App Secret",
+      validate: (value) => (value?.trim() ? undefined : "Required"),
+    }),
+  ).trim();
+  return { appId, appSecret };
+}
+
 function setFeishuGroupPolicy(
   cfg: ClawdbotConfig,
   groupPolicy: "open" | "allowlist" | "disabled",
@@ -210,18 +229,9 @@ export const feishuOnboardingAdapter: ChannelOnboardingAdapter = {
           },
         };
       } else {
-        appId = String(
-          await prompter.text({
-            message: "Enter Feishu App ID",
-            validate: (value) => (value?.trim() ? undefined : "Required"),
-          }),
-        ).trim();
-        appSecret = String(
-          await prompter.text({
-            message: "Enter Feishu App Secret",
-            validate: (value) => (value?.trim() ? undefined : "Required"),
-          }),
-        ).trim();
+        const entered = await promptFeishuCredentials(prompter);
+        appId = entered.appId;
+        appSecret = entered.appSecret;
       }
     } else if (hasConfigCreds) {
       const keep = await prompter.confirm({
@@ -229,32 +239,14 @@ export const feishuOnboardingAdapter: ChannelOnboardingAdapter = {
         initialValue: true,
       });
       if (!keep) {
-        appId = String(
-          await prompter.text({
-            message: "Enter Feishu App ID",
-            validate: (value) => (value?.trim() ? undefined : "Required"),
-          }),
-        ).trim();
-        appSecret = String(
-          await prompter.text({
-            message: "Enter Feishu App Secret",
-            validate: (value) => (value?.trim() ? undefined : "Required"),
-          }),
-        ).trim();
+        const entered = await promptFeishuCredentials(prompter);
+        appId = entered.appId;
+        appSecret = entered.appSecret;
       }
     } else {
-      appId = String(
-        await prompter.text({
-          message: "Enter Feishu App ID",
-          validate: (value) => (value?.trim() ? undefined : "Required"),
-        }),
-      ).trim();
-      appSecret = String(
-        await prompter.text({
-          message: "Enter Feishu App Secret",
-          validate: (value) => (value?.trim() ? undefined : "Required"),
-        }),
-      ).trim();
+      const entered = await promptFeishuCredentials(prompter);
+      appId = entered.appId;
+      appSecret = entered.appSecret;
     }
 
     if (appId && appSecret) {

package/src/policy.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest";
+import { isFeishuGroupAllowed, resolveFeishuAllowlistMatch } from "./policy.js";
+
+describe("feishu policy", () => {
+  describe("resolveFeishuAllowlistMatch", () => {
+    it("allows wildcard", () => {
+      expect(
+        resolveFeishuAllowlistMatch({
+          allowFrom: ["*"],
+          senderId: "ou-attacker",
+        }),
+      ).toEqual({ allowed: true, matchKey: "*", matchSource: "wildcard" });
+    });
+
+    it("matches normalized ID entries", () => {
+      expect(
+        resolveFeishuAllowlistMatch({
+          allowFrom: ["feishu:user:OU_ALLOWED"],
+          senderId: "ou_allowed",
+        }),
+      ).toEqual({ allowed: true, matchKey: "ou_allowed", matchSource: "id" });
+    });
+
+    it("supports user_id as an additional immutable sender candidate", () => {
+      expect(
+        resolveFeishuAllowlistMatch({
+          allowFrom: ["on_user_123"],
+          senderId: "ou_other",
+          senderIds: ["on_user_123"],
+        }),
+      ).toEqual({ allowed: true, matchKey: "on_user_123", matchSource: "id" });
+    });
+
+    it("does not authorize based on display-name collision", () => {
+      const victimOpenId = "ou_4f4ec5aa111122223333444455556666";
+
+      expect(
+        resolveFeishuAllowlistMatch({
+          allowFrom: [victimOpenId],
+          senderId: "ou_attacker_real_open_id",
+          senderIds: ["on_attacker_user_id"],
+          senderName: victimOpenId,
+        }),
+      ).toEqual({ allowed: false });
+    });
+  });
+
+  describe("isFeishuGroupAllowed", () => {
+    it("matches group IDs with chat: prefix", () => {
+      expect(
+        isFeishuGroupAllowed({
+          groupPolicy: "allowlist",
+          allowFrom: ["chat:oc_group_123"],
+          senderId: "oc_group_123",
+        }),
+      ).toBe(true);
+    });
+  });
+});

package/src/policy.ts

@@ -3,17 +3,52 @@ import type {
   ChannelGroupContext,
   GroupToolPolicyConfig,
 } from "openclaw/plugin-sdk";
-import { resolveAllowlistMatchSimple } from "openclaw/plugin-sdk";
+import { normalizeFeishuTarget } from "./targets.js";
 import type { FeishuConfig, FeishuGroupConfig } from "./types.js";
 
-export type FeishuAllowlistMatch = AllowlistMatch<"wildcard" | "id" | "name">;
+export type FeishuAllowlistMatch = AllowlistMatch<"wildcard" | "id">;
+
+function normalizeFeishuAllowEntry(raw: string): string {
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    return "";
+  }
+  if (trimmed === "*") {
+    return "*";
+  }
+  const withoutProviderPrefix = trimmed.replace(/^feishu:/i, "");
+  const normalized = normalizeFeishuTarget(withoutProviderPrefix) ?? withoutProviderPrefix;
+  return normalized.trim().toLowerCase();
+}
 
 export function resolveFeishuAllowlistMatch(params: {
   allowFrom: Array<string | number>;
   senderId: string;
+  senderIds?: Array<string | null | undefined>;
   senderName?: string | null;
 }): FeishuAllowlistMatch {
-  return resolveAllowlistMatchSimple(params);
+  const allowFrom = params.allowFrom
+    .map((entry) => normalizeFeishuAllowEntry(String(entry)))
+    .filter(Boolean);
+  if (allowFrom.length === 0) {
+    return { allowed: false };
+  }
+  if (allowFrom.includes("*")) {
+    return { allowed: true, matchKey: "*", matchSource: "wildcard" };
+  }
+
+  // Feishu allowlists are ID-based; mutable display names must never grant access.
+  const senderCandidates = [params.senderId, ...(params.senderIds ?? [])]
+    .map((entry) => normalizeFeishuAllowEntry(String(entry ?? "")))
+    .filter(Boolean);
+
+  for (const senderId of senderCandidates) {
+    if (allowFrom.includes(senderId)) {
+      return { allowed: true, matchKey: senderId, matchSource: "id" };
+    }
+  }
+
+  return { allowed: false };
 }
 
 export function resolveFeishuGroupConfig(params: {
@@ -56,6 +91,7 @@ export function isFeishuGroupAllowed(params: {
   groupPolicy: "open" | "allowlist" | "disabled";
   allowFrom: Array<string | number>;
   senderId: string;
+  senderIds?: Array<string | null | undefined>;
   senderName?: string | null;
 }): boolean {
   const { groupPolicy } = params;

package/src/send-target.ts

@@ -0,0 +1,25 @@
+import type { ClawdbotConfig } from "openclaw/plugin-sdk";
+import { resolveFeishuAccount } from "./accounts.js";
+import { createFeishuClient } from "./client.js";
+import { resolveReceiveIdType, normalizeFeishuTarget } from "./targets.js";
+
+export function resolveFeishuSendTarget(params: {
+  cfg: ClawdbotConfig;
+  to: string;
+  accountId?: string;
+}) {
+  const account = resolveFeishuAccount({ cfg: params.cfg, accountId: params.accountId });
+  if (!account.configured) {
+    throw new Error(`Feishu account "${account.accountId}" not configured`);
+  }
+  const client = createFeishuClient(account);
+  const receiveId = normalizeFeishuTarget(params.to);
+  if (!receiveId) {
+    throw new Error(`Invalid Feishu target: ${params.to}`);
+  }
+  return {
+    client,
+    receiveId,
+    receiveIdType: resolveReceiveIdType(receiveId),
+  };
+}

package/src/send.ts

@@ -5,8 +5,8 @@ import type { MentionTarget } from "./mention.js";
 import { buildMentionedMessage, buildMentionedCardContent } from "./mention.js";
 import { getFeishuRuntime } from "./runtime.js";
 import { assertFeishuMessageApiSuccess, toFeishuSendResult } from "./send-result.js";
-import { resolveReceiveIdType, normalizeFeishuTarget } from "./targets.js";
-import type { FeishuSendResult, ResolvedFeishuAccount } from "./types.js";
+import { resolveFeishuSendTarget } from "./send-target.js";
+import type { FeishuSendResult } from "./types.js";
 
 export type FeishuMessageInfo = {
   messageId: string;
@@ -128,18 +128,7 @@ export async function sendMessageFeishu(
   params: SendFeishuMessageParams,
 ): Promise<FeishuSendResult> {
   const { cfg, to, text, replyToMessageId, mentions, accountId } = params;
-  const account = resolveFeishuAccount({ cfg, accountId });
-  if (!account.configured) {
-    throw new Error(`Feishu account "${account.accountId}" not configured`);
-  }
-
-  const client = createFeishuClient(account);
-  const receiveId = normalizeFeishuTarget(to);
-  if (!receiveId) {
-    throw new Error(`Invalid Feishu target: ${to}`);
-  }
-
-  const receiveIdType = resolveReceiveIdType(receiveId);
+  const { client, receiveId, receiveIdType } = resolveFeishuSendTarget({ cfg, to, accountId });
   const tableMode = getFeishuRuntime().channel.text.resolveMarkdownTableMode({
     cfg,
     channel: "feishu",
@@ -188,18 +177,7 @@ export type SendFeishuCardParams = {
 
 export async function sendCardFeishu(params: SendFeishuCardParams): Promise<FeishuSendResult> {
   const { cfg, to, card, replyToMessageId, accountId } = params;
-  const account = resolveFeishuAccount({ cfg, accountId });
-  if (!account.configured) {
-    throw new Error(`Feishu account "${account.accountId}" not configured`);
-  }
-
-  const client = createFeishuClient(account);
-  const receiveId = normalizeFeishuTarget(to);
-  if (!receiveId) {
-    throw new Error(`Invalid Feishu target: ${to}`);
-  }
-
-  const receiveIdType = resolveReceiveIdType(receiveId);
+  const { client, receiveId, receiveIdType } = resolveFeishuSendTarget({ cfg, to, accountId });
   const content = JSON.stringify(card);
 
   if (replyToMessageId) {