@openclaw/feishu 2026.3.13 → 2026.5.2-beta.1

package/src/runtime.ts

@@ -1,6 +1,9 @@
-import { createPluginRuntimeStore } from "openclaw/plugin-sdk/compat";
-import type { PluginRuntime } from "openclaw/plugin-sdk/feishu";
+import type { PluginRuntime } from "openclaw/plugin-sdk/core";
+import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
 
 const { setRuntime: setFeishuRuntime, getRuntime: getFeishuRuntime } =
-  createPluginRuntimeStore<PluginRuntime>("Feishu runtime not initialized");
+  createPluginRuntimeStore<PluginRuntime>({
+    pluginId: "feishu",
+    errorMessage: "Feishu runtime not initialized",
+  });
 export { getFeishuRuntime, setFeishuRuntime };

package/src/secret-contract.ts

@@ -0,0 +1,145 @@
+import {
+  collectConditionalChannelFieldAssignments,
+  collectSimpleChannelFieldAssignments,
+  getChannelSurface,
+  hasOwnProperty,
+  normalizeSecretStringValue,
+  type ResolverContext,
+  type SecretDefaults,
+  type SecretTargetRegistryEntry,
+} from "openclaw/plugin-sdk/channel-secret-basic-runtime";
+
+export const secretTargetRegistryEntries: SecretTargetRegistryEntry[] = [
+  {
+    id: "channels.feishu.accounts.*.appSecret",
+    targetType: "channels.feishu.accounts.*.appSecret",
+    configFile: "openclaw.json",
+    pathPattern: "channels.feishu.accounts.*.appSecret",
+    secretShape: "secret_input",
+    expectedResolvedValue: "string",
+    includeInPlan: true,
+    includeInConfigure: true,
+    includeInAudit: true,
+  },
+  {
+    id: "channels.feishu.accounts.*.encryptKey",
+    targetType: "channels.feishu.accounts.*.encryptKey",
+    configFile: "openclaw.json",
+    pathPattern: "channels.feishu.accounts.*.encryptKey",
+    secretShape: "secret_input",
+    expectedResolvedValue: "string",
+    includeInPlan: true,
+    includeInConfigure: true,
+    includeInAudit: true,
+  },
+  {
+    id: "channels.feishu.accounts.*.verificationToken",
+    targetType: "channels.feishu.accounts.*.verificationToken",
+    configFile: "openclaw.json",
+    pathPattern: "channels.feishu.accounts.*.verificationToken",
+    secretShape: "secret_input",
+    expectedResolvedValue: "string",
+    includeInPlan: true,
+    includeInConfigure: true,
+    includeInAudit: true,
+  },
+  {
+    id: "channels.feishu.appSecret",
+    targetType: "channels.feishu.appSecret",
+    configFile: "openclaw.json",
+    pathPattern: "channels.feishu.appSecret",
+    secretShape: "secret_input",
+    expectedResolvedValue: "string",
+    includeInPlan: true,
+    includeInConfigure: true,
+    includeInAudit: true,
+  },
+  {
+    id: "channels.feishu.encryptKey",
+    targetType: "channels.feishu.encryptKey",
+    configFile: "openclaw.json",
+    pathPattern: "channels.feishu.encryptKey",
+    secretShape: "secret_input",
+    expectedResolvedValue: "string",
+    includeInPlan: true,
+    includeInConfigure: true,
+    includeInAudit: true,
+  },
+  {
+    id: "channels.feishu.verificationToken",
+    targetType: "channels.feishu.verificationToken",
+    configFile: "openclaw.json",
+    pathPattern: "channels.feishu.verificationToken",
+    secretShape: "secret_input",
+    expectedResolvedValue: "string",
+    includeInPlan: true,
+    includeInConfigure: true,
+    includeInAudit: true,
+  },
+];
+
+export function collectRuntimeConfigAssignments(params: {
+  config: { channels?: Record<string, unknown> };
+  defaults?: SecretDefaults;
+  context: ResolverContext;
+}): void {
+  const resolved = getChannelSurface(params.config, "feishu");
+  if (!resolved) {
+    return;
+  }
+  const { channel: feishu, surface } = resolved;
+  collectSimpleChannelFieldAssignments({
+    channelKey: "feishu",
+    field: "appSecret",
+    channel: feishu,
+    surface,
+    defaults: params.defaults,
+    context: params.context,
+    topInactiveReason: "no enabled account inherits this top-level Feishu appSecret.",
+    accountInactiveReason: "Feishu account is disabled.",
+  });
+  const baseConnectionMode =
+    normalizeSecretStringValue(feishu.connectionMode) === "webhook" ? "webhook" : "websocket";
+  const resolveAccountMode = (account: Record<string, unknown>) =>
+    hasOwnProperty(account, "connectionMode")
+      ? normalizeSecretStringValue(account.connectionMode)
+      : baseConnectionMode;
+  collectConditionalChannelFieldAssignments({
+    channelKey: "feishu",
+    field: "encryptKey",
+    channel: feishu,
+    surface,
+    defaults: params.defaults,
+    context: params.context,
+    topLevelActiveWithoutAccounts: baseConnectionMode === "webhook",
+    topLevelInheritedAccountActive: ({ account, enabled }) =>
+      enabled &&
+      !hasOwnProperty(account, "encryptKey") &&
+      resolveAccountMode(account) === "webhook",
+    accountActive: ({ account, enabled }) => enabled && resolveAccountMode(account) === "webhook",
+    topInactiveReason: "no enabled Feishu webhook-mode surface inherits this top-level encryptKey.",
+    accountInactiveReason: "Feishu account is disabled or not running in webhook mode.",
+  });
+  collectConditionalChannelFieldAssignments({
+    channelKey: "feishu",
+    field: "verificationToken",
+    channel: feishu,
+    surface,
+    defaults: params.defaults,
+    context: params.context,
+    topLevelActiveWithoutAccounts: baseConnectionMode === "webhook",
+    topLevelInheritedAccountActive: ({ account, enabled }) =>
+      enabled &&
+      !hasOwnProperty(account, "verificationToken") &&
+      resolveAccountMode(account) === "webhook",
+    accountActive: ({ account, enabled }) => enabled && resolveAccountMode(account) === "webhook",
+    topInactiveReason:
+      "no enabled Feishu webhook-mode surface inherits this top-level verificationToken.",
+    accountInactiveReason: "Feishu account is disabled or not running in webhook mode.",
+  });
+}
+
+export const channelSecrets = {
+  secretTargetRegistryEntries,
+  collectRuntimeConfigAssignments,
+};

package/src/secret-input.ts

@@ -1,13 +1 @@
-import {
-  buildSecretInputSchema,
-  hasConfiguredSecretInput,
-  normalizeResolvedSecretInputString,
-  normalizeSecretInputString,
-} from "openclaw/plugin-sdk/feishu";
-
-export {
-  buildSecretInputSchema,
-  hasConfiguredSecretInput,
-  normalizeResolvedSecretInputString,
-  normalizeSecretInputString,
-};
+export { buildSecretInputSchema, hasConfiguredSecretInput } from "openclaw/plugin-sdk/secret-input";

package/src/security-audit-shared.ts

@@ -0,0 +1,69 @@
+import { hasConfiguredSecretInput } from "openclaw/plugin-sdk/secret-input";
+import type { OpenClawConfig } from "../runtime-api.js";
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+function hasNonEmptyString(value: unknown): boolean {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+function isFeishuDocToolEnabled(cfg: OpenClawConfig): boolean {
+  const channels = asRecord(cfg.channels);
+  const feishu = asRecord(channels?.feishu);
+  if (!feishu || feishu.enabled === false) {
+    return false;
+  }
+
+  const baseTools = asRecord(feishu.tools);
+  const baseDocEnabled = baseTools?.doc !== false;
+  const baseAppId = hasNonEmptyString(feishu.appId);
+  const baseAppSecret = hasConfiguredSecretInput(feishu.appSecret, cfg.secrets?.defaults);
+  const baseConfigured = baseAppId && baseAppSecret;
+
+  const accounts = asRecord(feishu.accounts);
+  if (!accounts || Object.keys(accounts).length === 0) {
+    return baseDocEnabled && baseConfigured;
+  }
+
+  for (const accountValue of Object.values(accounts)) {
+    const account = asRecord(accountValue) ?? {};
+    if (account.enabled === false) {
+      continue;
+    }
+    const accountTools = asRecord(account.tools);
+    const effectiveTools = accountTools ?? baseTools;
+    const docEnabled = effectiveTools?.doc !== false;
+    if (!docEnabled) {
+      continue;
+    }
+    const accountConfigured =
+      (hasNonEmptyString(account.appId) || baseAppId) &&
+      (hasConfiguredSecretInput(account.appSecret, cfg.secrets?.defaults) || baseAppSecret);
+    if (accountConfigured) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+export function collectFeishuSecurityAuditFindings(params: { cfg: OpenClawConfig }) {
+  if (!isFeishuDocToolEnabled(params.cfg)) {
+    return [];
+  }
+  return [
+    {
+      checkId: "channels.feishu.doc_owner_open_id",
+      severity: "warn" as const,
+      title: "Feishu doc create can grant requester permissions",
+      detail:
+        'channels.feishu tools include "doc"; feishu_doc action "create" can grant document access to the trusted requesting Feishu user.',
+      remediation:
+        "Disable channels.feishu.tools.doc when not needed, and restrict tool access for untrusted prompts.",
+    },
+  ];
+}

package/src/security-audit.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from "vitest";
+import type { OpenClawConfig } from "../runtime-api.js";
+import { collectFeishuSecurityAuditFindings } from "./security-audit.js";
+
+describe("Feishu security audit findings", () => {
+  it.each([
+    {
+      name: "warns when doc tool is enabled because create can grant requester access",
+      cfg: {
+        channels: {
+          feishu: {
+            appId: "cli_test",
+            appSecret: "secret_test",
+          },
+        },
+      } satisfies OpenClawConfig,
+      expectedFinding: "channels.feishu.doc_owner_open_id",
+    },
+    {
+      name: "treats SecretRef appSecret as configured for doc tool risk detection",
+      cfg: {
+        channels: {
+          feishu: {
+            appId: "cli_test",
+            appSecret: {
+              source: "env",
+              provider: "default",
+              id: "FEISHU_APP_SECRET",
+            },
+          },
+        },
+      } satisfies OpenClawConfig,
+      expectedFinding: "channels.feishu.doc_owner_open_id",
+    },
+    {
+      name: "does not warn for doc grant risk when doc tools are disabled",
+      cfg: {
+        channels: {
+          feishu: {
+            appId: "cli_test",
+            appSecret: "secret_test",
+            tools: { doc: false },
+          },
+        },
+      } satisfies OpenClawConfig,
+      expectedNoFinding: "channels.feishu.doc_owner_open_id",
+    },
+  ])("$name", ({ cfg, expectedFinding, expectedNoFinding }) => {
+    const findings = collectFeishuSecurityAuditFindings({ cfg });
+    if (expectedFinding) {
+      expect(
+        findings.some(
+          (finding) => finding.checkId === expectedFinding && finding.severity === "warn",
+        ),
+      ).toBe(true);
+    }
+    if (expectedNoFinding) {
+      expect(findings.some((finding) => finding.checkId === expectedNoFinding)).toBe(false);
+    }
+  });
+});

package/src/security-audit.ts

@@ -0,0 +1 @@
+export { collectFeishuSecurityAuditFindings } from "./security-audit-shared.js";

package/src/send-result.ts

@@ -1,4 +1,4 @@
-export type FeishuMessageApiResponse = {
+type FeishuMessageApiResponse = {
   code?: number;
   msg?: string;
   data?: {

package/src/send-target.test.ts

@@ -1,22 +1,28 @@
-import type { ClawdbotConfig } from "openclaw/plugin-sdk/feishu";
-import { beforeEach, describe, expect, it, vi } from "vitest";
-import { resolveFeishuSendTarget } from "./send-target.js";
+import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import type { ClawdbotConfig } from "../runtime-api.js";
 
 const resolveFeishuAccountMock = vi.hoisted(() => vi.fn());
 const createFeishuClientMock = vi.hoisted(() => vi.fn());
 
 vi.mock("./accounts.js", () => ({
   resolveFeishuAccount: resolveFeishuAccountMock,
+  resolveFeishuRuntimeAccount: resolveFeishuAccountMock,
 }));
 
 vi.mock("./client.js", () => ({
   createFeishuClient: createFeishuClientMock,
 }));
 
+let resolveFeishuSendTarget: typeof import("./send-target.js").resolveFeishuSendTarget;
+
 describe("resolveFeishuSendTarget", () => {
   const cfg = {} as ClawdbotConfig;
   const client = { id: "client" };
 
+  beforeAll(async () => {
+    ({ resolveFeishuSendTarget } = await import("./send-target.js"));
+  });
+
   beforeEach(() => {
     resolveFeishuAccountMock.mockReset().mockReturnValue({
       accountId: "default",

package/src/send-target.ts

@@ -1,15 +1,21 @@
-import type { ClawdbotConfig } from "openclaw/plugin-sdk/feishu";
-import { resolveFeishuAccount } from "./accounts.js";
+import type { ClawdbotConfig } from "../runtime-api.js";
+import { resolveFeishuRuntimeAccount } from "./accounts.js";
 import { createFeishuClient } from "./client.js";
 import { resolveReceiveIdType, normalizeFeishuTarget } from "./targets.js";
 
+type FeishuSendTarget = {
+  client: ReturnType<typeof createFeishuClient>;
+  receiveId: string;
+  receiveIdType: ReturnType<typeof resolveReceiveIdType>;
+};
+
 export function resolveFeishuSendTarget(params: {
   cfg: ClawdbotConfig;
   to: string;
   accountId?: string;
-}) {
+}): FeishuSendTarget {
   const target = params.to.trim();
-  const account = resolveFeishuAccount({ cfg: params.cfg, accountId: params.accountId });
+  const account = resolveFeishuRuntimeAccount({ cfg: params.cfg, accountId: params.accountId });
   if (!account.configured) {
     throw new Error(`Feishu account "${account.accountId}" not configured`);
   }

package/src/send.reply-fallback.test.ts

@@ -1,4 +1,4 @@
-import { beforeEach, describe, expect, it, vi } from "vitest";
+import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 
 const resolveFeishuSendTargetMock = vi.hoisted(() => vi.fn());
 const resolveMarkdownTableModeMock = vi.hoisted(() => vi.fn(() => "preserve"));
@@ -9,6 +9,7 @@ vi.mock("./send-target.js", () => ({
 }));
 
 vi.mock("./runtime.js", () => ({
+  setFeishuRuntime: vi.fn(),
   getFeishuRuntime: () => ({
     channel: {
       text: {
@@ -19,7 +20,8 @@ vi.mock("./runtime.js", () => ({
   }),
 }));
 
-import { sendCardFeishu, sendMessageFeishu } from "./send.js";
+let sendCardFeishu: typeof import("./send.js").sendCardFeishu;
+let sendMessageFeishu: typeof import("./send.js").sendMessageFeishu;
 
 describe("Feishu reply fallback for withdrawn/deleted targets", () => {
   const replyMock = vi.fn();
@@ -35,6 +37,10 @@ describe("Feishu reply fallback for withdrawn/deleted targets", () => {
     expect(result.messageId).toBe(expectedMessageId);
   }
 
+  beforeAll(async () => {
+    ({ sendCardFeishu, sendMessageFeishu } = await import("./send.js"));
+  });
+
   beforeEach(() => {
     vi.clearAllMocks();
     resolveFeishuSendTargetMock.mockReturnValue({
@@ -51,6 +57,34 @@ describe("Feishu reply fallback for withdrawn/deleted targets", () => {
     });
   });
 
+  it("preserves Feishu diagnostics when direct sends reject before response checks", async () => {
+    const apiError = Object.assign(new Error("Request failed with status code 400"), {
+      response: {
+        status: 400,
+        data: {
+          code: 9499,
+          msg: "Bad Request",
+          error: {
+            log_id: "202604291247104BEF4C42D2420A9AD569",
+            troubleshooter:
+              "https://open.feishu.cn/search?log_id=202604291247104BEF4C42D2420A9AD569",
+          },
+        },
+      },
+    });
+    createMock.mockRejectedValue(apiError);
+
+    await expect(
+      sendMessageFeishu({
+        cfg: {} as never,
+        to: "user:ou_target",
+        text: "hello",
+      }),
+    ).rejects.toThrow(
+      /Feishu send failed: .*"http_status":400.*"feishu_code":9499.*"feishu_msg":"Bad Request".*"feishu_log_id":"202604291247104BEF4C42D2420A9AD569".*"feishu_troubleshooter":"https:\/\/open\.feishu\.cn\/search\?log_id=202604291247104BEF4C42D2420A9AD569"/,
+    );
+  });
+
   it("falls back to create for withdrawn post replies", async () => {
     replyMock.mockResolvedValue({
       code: 230011,
@@ -171,6 +205,75 @@ describe("Feishu reply fallback for withdrawn/deleted targets", () => {
     expect(createMock).not.toHaveBeenCalled();
   });
 
+  it("fails thread replies instead of falling back to a top-level send", async () => {
+    replyMock.mockResolvedValue({
+      code: 230011,
+      msg: "The message was withdrawn.",
+    });
+
+    await expect(
+      sendMessageFeishu({
+        cfg: {} as never,
+        to: "chat:oc_group_1",
+        text: "hello",
+        replyToMessageId: "om_parent",
+        replyInThread: true,
+      }),
+    ).rejects.toThrow(
+      "Feishu thread reply failed: reply target is unavailable and cannot safely fall back to a top-level send.",
+    );
+
+    expect(createMock).not.toHaveBeenCalled();
+    expect(replyMock).toHaveBeenCalledWith({
+      path: { message_id: "om_parent" },
+      data: expect.objectContaining({
+        reply_in_thread: true,
+      }),
+    });
+  });
+
+  it("fails thrown withdrawn thread replies instead of falling back to create", async () => {
+    const sdkError = Object.assign(new Error("request failed"), { code: 230011 });
+    replyMock.mockRejectedValue(sdkError);
+
+    await expect(
+      sendMessageFeishu({
+        cfg: {} as never,
+        to: "chat:oc_group_1",
+        text: "hello",
+        replyToMessageId: "om_parent",
+        replyInThread: true,
+      }),
+    ).rejects.toThrow(
+      "Feishu thread reply failed: reply target is unavailable and cannot safely fall back to a top-level send.",
+    );
+
+    expect(createMock).not.toHaveBeenCalled();
+  });
+
+  it("still falls back for non-thread replies to withdrawn targets", async () => {
+    replyMock.mockResolvedValue({
+      code: 230011,
+      msg: "The message was withdrawn.",
+    });
+    createMock.mockResolvedValue({
+      code: 0,
+      data: { message_id: "om_non_thread_fallback" },
+    });
+
+    await expectFallbackResult(
+      () =>
+        sendMessageFeishu({
+          cfg: {} as never,
+          to: "user:ou_target",
+          text: "hello",
+          replyToMessageId: "om_parent",
+          replyInThread: false,
+        }),
+      "om_non_thread_fallback",
+    );
+  });
+
   it("re-throws non-withdrawn thrown errors for card messages", async () => {
     const sdkError = Object.assign(new Error("permission denied"), { code: 99991401 });
     replyMock.mockRejectedValue(sdkError);