@kodelyth/feishu 2026.5.39 → 2026.5.42

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kodelyth/feishu",
-  "version": "2026.5.39",
+  "version": "2026.5.42",
   "description": "Klaw Feishu/Lark channel plugin (community maintained by @m1heng)",
   "repository": {
     "type": "git",
@@ -14,7 +14,7 @@
   },
   "devDependencies": {
     "@kodelyth/plugin-sdk": "1.0.1",
-    "@kodelyth/klaw": "2026.5.41"
+    "@kodelyth/klaw": "2026.5.42"
   },
   "peerDependencies": {
     "@kodelyth/klaw": ">=2026.5.19"
@@ -26,9 +26,9 @@
   },
   "klaw": {
     "extensions": [
-      "./index.js"
+      "./index.ts"
     ],
-    "setupEntry": "./setup-entry.js",
+    "setupEntry": "./setup-entry.ts",
     "channel": {
       "id": "feishu",
       "label": "Feishu",

package/runtime-api.ts

@@ -0,0 +1,52 @@
+// Private runtime barrel for the bundled Feishu extension.
+// Keep this barrel thin and generic-only.
+
+export type {
+  AllowlistMatch,
+  AnyAgentTool,
+  BaseProbeResult,
+  ChannelGroupContext,
+  ChannelMessageActionName,
+  ChannelMeta,
+  ChannelOutboundAdapter,
+  ChannelPlugin,
+  HistoryEntry,
+  KlawConfig,
+  KlawPluginApi,
+  OutboundIdentity,
+  PluginRuntime,
+  ReplyPayload,
+} from "klaw/plugin-sdk/core";
+export type { KlawConfig as ClawdbotConfig } from "klaw/plugin-sdk/core";
+export type { RuntimeEnv } from "klaw/plugin-sdk/runtime";
+export type { GroupToolPolicyConfig } from "klaw/plugin-sdk/config-contracts";
+export {
+  DEFAULT_ACCOUNT_ID,
+  buildChannelConfigSchema,
+  createActionGate,
+  createDedupeCache,
+} from "klaw/plugin-sdk/core";
+export {
+  PAIRING_APPROVED_MESSAGE,
+  buildProbeChannelStatusSummary,
+  createDefaultChannelRuntimeState,
+} from "klaw/plugin-sdk/channel-status";
+export { buildAgentMediaPayload } from "klaw/plugin-sdk/agent-media-payload";
+export { createChannelPairingController } from "klaw/plugin-sdk/channel-pairing";
+export { createReplyPrefixContext } from "klaw/plugin-sdk/channel-message";
+export {
+  evaluateSupplementalContextVisibility,
+  filterSupplementalContextItems,
+  resolveChannelContextVisibilityMode,
+} from "klaw/plugin-sdk/context-visibility-runtime";
+export { loadSessionStore, resolveSessionStoreEntry } from "klaw/plugin-sdk/session-store-runtime";
+export { readJsonFileWithFallback } from "klaw/plugin-sdk/json-store";
+export { createPersistentDedupe } from "klaw/plugin-sdk/persistent-dedupe";
+export { normalizeAgentId } from "klaw/plugin-sdk/routing";
+export { chunkTextForOutbound } from "klaw/plugin-sdk/text-chunking";
+export {
+  isRequestBodyLimitError,
+  readRequestBodyWithLimit,
+  requestBodyErrorToText,
+} from "klaw/plugin-sdk/webhook-ingress";
+export { setFeishuRuntime } from "./src/runtime.js";

package/secret-contract-api.ts

@@ -0,0 +1,5 @@
+export {
+  channelSecrets,
+  collectRuntimeConfigAssignments,
+  secretTargetRegistryEntries,
+} from "./src/secret-contract.js";

package/security-contract-api.ts

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

package/session-key-api.ts

@@ -0,0 +1 @@
+export { resolveFeishuSessionConversation as resolveSessionConversation } from "./src/session-conversation.js";

package/setup-api.ts

@@ -0,0 +1,3 @@
+export { feishuPlugin } from "./src/channel.js";
+export { feishuSetupAdapter } from "./src/setup-core.js";
+export { feishuSetupWizard } from "./src/setup-surface.js";

package/setup-entry.test.ts

@@ -0,0 +1,19 @@
+import { afterAll, describe, expect, it, vi } from "vitest";
+
+vi.mock("@larksuiteoapi/node-sdk", () => {
+  throw new Error("setup entry must not load the Feishu SDK");
+});
+
+describe("feishu setup entry", () => {
+  afterAll(() => {
+    vi.doUnmock("@larksuiteoapi/node-sdk");
+    vi.resetModules();
+  });
+
+  it("declares the setup entry without importing Feishu runtime dependencies", async () => {
+    const { default: setupEntry } = await import("./setup-entry.js");
+
+    expect(setupEntry.kind).toBe("bundled-channel-setup-entry");
+    expect(typeof setupEntry.loadSetupPlugin).toBe("function");
+  });
+});

package/setup-entry.ts

@@ -0,0 +1,13 @@
+import { defineBundledChannelSetupEntry } from "klaw/plugin-sdk/channel-entry-contract";
+
+export default defineBundledChannelSetupEntry({
+  importMetaUrl: import.meta.url,
+  plugin: {
+    specifier: "./setup-api.js",
+    exportName: "feishuPlugin",
+  },
+  secrets: {
+    specifier: "./secret-contract-api.js",
+    exportName: "channelSecrets",
+  },
+});

package/src/accounts.test.ts

@@ -0,0 +1,480 @@
+import { describe, expect, it } from "vitest";
+import {
+  FeishuSecretRefUnavailableError,
+  inspectFeishuCredentials,
+  listFeishuAccountIds,
+  resolveDefaultFeishuAccountId,
+  resolveDefaultFeishuAccountSelection,
+  resolveFeishuAccount,
+  resolveFeishuCredentials,
+  resolveFeishuRuntimeAccount,
+} from "./accounts.js";
+import type { FeishuConfig } from "./types.js";
+
+function makeDefaultAndRouterAccounts() {
+  return {
+    default: { appId: "cli_default", appSecret: "secret_default" }, // pragma: allowlist secret
+    "router-d": { appId: "cli_router", appSecret: "secret_router" }, // pragma: allowlist secret
+  };
+}
+
+function expectExplicitDefaultAccountSelection(
+  account: ReturnType<typeof resolveFeishuAccount>,
+  appId: string,
+) {
+  expect(account.accountId).toBe("router-d");
+  expect(account.selectionSource).toBe("explicit-default");
+  expect(account.configured).toBe(true);
+  expect(account.appId).toBe(appId);
+}
+
+function withEnvVar(key: string, value: string | undefined, run: () => void) {
+  const prev = process.env[key];
+  if (value === undefined) {
+    delete process.env[key];
+  } else {
+    process.env[key] = value;
+  }
+  try {
+    run();
+  } finally {
+    if (prev === undefined) {
+      delete process.env[key];
+    } else {
+      process.env[key] = prev;
+    }
+  }
+}
+
+function asConfig(config: Partial<FeishuConfig>): FeishuConfig {
+  return config as unknown as FeishuConfig;
+}
+
+function expectUnresolvedEnvSecretRefError(key: string) {
+  expect(() =>
+    resolveFeishuCredentials(
+      asConfig({
+        appId: "cli_123",
+        appSecret: { source: "env", provider: "default", id: key } as never,
+      }),
+    ),
+  ).toThrow(/unresolved SecretRef/i);
+}
+
+describe("resolveDefaultFeishuAccountId", () => {
+  it("preserves top-level default account when named accounts are configured", () => {
+    const cfg = {
+      channels: {
+        feishu: {
+          appId: "cli_default",
+          appSecret: "secret_default",
+          accounts: {
+            work: { enabled: false },
+          },
+        },
+      },
+    };
+
+    expect(listFeishuAccountIds(cfg as never)).toEqual(["default", "work"]);
+    expect(resolveDefaultFeishuAccountId(cfg as never)).toBe("default");
+  });
+
+  it("prefers channels.feishu.defaultAccount when configured", () => {
+    const cfg = {
+      channels: {
+        feishu: {
+          defaultAccount: "router-d",
+          accounts: makeDefaultAndRouterAccounts(),
+        },
+      },
+    };
+
+    expect(resolveDefaultFeishuAccountId(cfg as never)).toBe("router-d");
+  });
+
+  it("normalizes configured defaultAccount before lookup", () => {
+    const cfg = {
+      channels: {
+        feishu: {
+          defaultAccount: "Router D",
+          accounts: {
+            "router-d": { appId: "cli_router", appSecret: "secret_router" }, // pragma: allowlist secret
+          },
+        },
+      },
+    };
+
+    expect(resolveDefaultFeishuAccountId(cfg as never)).toBe("router-d");
+  });
+
+  it("keeps configured defaultAccount even when not present in accounts map", () => {
+    const cfg = {
+      channels: {
+        feishu: {
+          defaultAccount: "router-d",
+          accounts: {
+            default: { appId: "cli_default", appSecret: "secret_default" }, // pragma: allowlist secret
+            zeta: { appId: "cli_zeta", appSecret: "secret_zeta" }, // pragma: allowlist secret
+          },
+        },
+      },
+    };
+
+    expect(resolveDefaultFeishuAccountId(cfg as never)).toBe("router-d");
+  });
+
+  it("falls back to literal default account id when present", () => {
+    const cfg = {
+      channels: {
+        feishu: {
+          accounts: {
+            default: { appId: "cli_default", appSecret: "secret_default" }, // pragma: allowlist secret
+            zeta: { appId: "cli_zeta", appSecret: "secret_zeta" }, // pragma: allowlist secret
+          },
+        },
+      },
+    };
+
+    expect(resolveDefaultFeishuAccountId(cfg as never)).toBe("default");
+  });
+
+  it("reports selection source for configured defaults and mapped defaults", () => {
+    const explicitDefaultCfg = {
+      channels: {
+        feishu: {
+          defaultAccount: "router-d",
+          accounts: {},
+        },
+      },
+    };
+    expect(resolveDefaultFeishuAccountSelection(explicitDefaultCfg as never)).toEqual({
+      accountId: "router-d",
+      source: "explicit-default",
+    });
+
+    const mappedDefaultCfg = {
+      channels: {
+        feishu: {
+          accounts: {
+            default: { appId: "cli_default", appSecret: "secret_default" }, // pragma: allowlist secret
+          },
+        },
+      },
+    };
+    expect(resolveDefaultFeishuAccountSelection(mappedDefaultCfg as never)).toEqual({
+      accountId: "default",
+      source: "mapped-default",
+    });
+  });
+});
+
+describe("resolveFeishuCredentials", () => {
+  it("throws unresolved SecretRef errors by default for unsupported secret sources", () => {
+    expect(() =>
+      resolveFeishuCredentials(
+        asConfig({
+          appId: "cli_123",
+          appSecret: { source: "file", provider: "default", id: "path/to/secret" } as never,
+        }),
+      ),
+    ).toThrow(/unresolved SecretRef/i);
+  });
+
+  it("returns null (without throwing) when unresolved SecretRef is allowed", () => {
+    const creds = resolveFeishuCredentials(
+      asConfig({
+        appId: "cli_123",
+        appSecret: { source: "file", provider: "default", id: "path/to/secret" } as never,
+      }),
+      { allowUnresolvedSecretRef: true },
+    );
+
+    expect(creds).toBeNull();
+  });
+
+  it("supports explicit inspect mode for unresolved SecretRefs", () => {
+    const creds = resolveFeishuCredentials(
+      asConfig({
+        appId: "cli_123",
+        appSecret: { source: "file", provider: "default", id: "path/to/secret" } as never,
+      }),
+      { mode: "inspect" },
+    );
+
+    expect(creds).toBeNull();
+  });
+
+  it("throws unresolved SecretRef error when env SecretRef points to missing env var", () => {
+    const key = "FEISHU_APP_SECRET_MISSING_TEST";
+    withEnvVar(key, undefined, () => {
+      expectUnresolvedEnvSecretRefError(key);
+    });
+  });
+
+  it("resolves env SecretRef objects when unresolved refs are allowed", () => {
+    const key = "FEISHU_APP_SECRET_TEST";
+    const prev = process.env[key];
+    process.env[key] = " secret_from_env ";
+
+    try {
+      const creds = resolveFeishuCredentials(
+        asConfig({
+          appId: "cli_123",
+          appSecret: { source: "env", provider: "default", id: key } as never,
+        }),
+        { allowUnresolvedSecretRef: true },
+      );
+
+      expect(creds).toEqual({
+        appId: "cli_123",
+        appSecret: "secret_from_env", // pragma: allowlist secret
+        encryptKey: undefined,
+        verificationToken: undefined,
+        domain: "feishu",
+      });
+    } finally {
+      if (prev === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = prev;
+      }
+    }
+  });
+
+  it("resolves env SecretRef with custom provider alias when unresolved refs are allowed", () => {
+    const key = "FEISHU_APP_SECRET_CUSTOM_PROVIDER_TEST";
+    const prev = process.env[key];
+    process.env[key] = " secret_from_env_alias ";
+
+    try {
+      const creds = resolveFeishuCredentials(
+        asConfig({
+          appId: "cli_123",
+          appSecret: { source: "env", provider: "corp-env", id: key } as never,
+        }),
+        { allowUnresolvedSecretRef: true },
+      );
+
+      expect(creds?.appSecret).toBe("secret_from_env_alias");
+    } finally {
+      if (prev === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = prev;
+      }
+    }
+  });
+
+  it("preserves unresolved SecretRef diagnostics for env refs in default mode", () => {
+    const key = "FEISHU_APP_SECRET_POLICY_TEST";
+    withEnvVar(key, "secret_from_env", () => {
+      expectUnresolvedEnvSecretRefError(key);
+    });
+  });
+
+  it("trims and returns credentials when values are valid strings", () => {
+    const creds = resolveFeishuCredentials(
+      asConfig({
+        appId: " cli_123 ",
+        appSecret: " secret_456 ",
+        encryptKey: " enc ",
+        verificationToken: " vt ",
+      }),
+    );
+
+    expect(creds).toEqual({
+      appId: "cli_123",
+      appSecret: "secret_456", // pragma: allowlist secret
+      encryptKey: "enc",
+      verificationToken: "vt",
+      domain: "feishu",
+    });
+  });
+
+  it("does not resolve encryptKey SecretRefs outside webhook mode", () => {
+    const creds = resolveFeishuCredentials(
+      asConfig({
+        connectionMode: "websocket",
+        appId: "cli_123",
+        appSecret: "secret_456",
+        encryptKey: { source: "file", provider: "default", id: "path/to/secret" } as never,
+      }),
+    );
+
+    expect(creds).toEqual({
+      appId: "cli_123",
+      appSecret: "secret_456", // pragma: allowlist secret
+      encryptKey: undefined,
+      verificationToken: undefined,
+      domain: "feishu",
+    });
+  });
+
+  it("keeps required credentials when optional event SecretRefs are unresolved in inspect mode", () => {
+    const creds = inspectFeishuCredentials(
+      asConfig({
+        appId: "cli_123",
+        appSecret: "secret_456",
+        verificationToken: { source: "file", provider: "default", id: "path/to/token" } as never,
+      }),
+    );
+
+    expect(creds).toEqual({
+      appId: "cli_123",
+      appSecret: "secret_456", // pragma: allowlist secret
+      encryptKey: undefined,
+      verificationToken: undefined,
+      domain: "feishu",
+    });
+  });
+});
+
+describe("resolveFeishuAccount", () => {
+  it("uses top-level credentials with configured default account id even without account map entry", () => {
+    const cfg = {
+      channels: {
+        feishu: {
+          defaultAccount: "router-d",
+          appId: "top_level_app",
+          appSecret: "top_level_secret", // pragma: allowlist secret
+          accounts: {
+            default: { appId: "cli_default", appSecret: "secret_default" }, // pragma: allowlist secret
+          },
+        },
+      },
+    };
+
+    const account = resolveFeishuAccount({ cfg: cfg as never, accountId: undefined });
+    expectExplicitDefaultAccountSelection(account, "top_level_app");
+  });
+
+  it("uses configured default account when accountId is omitted", () => {
+    const cfg = {
+      channels: {
+        feishu: {
+          defaultAccount: "router-d",
+          accounts: {
+            default: { enabled: true },
+            "router-d": { appId: "cli_router", appSecret: "secret_router", enabled: true }, // pragma: allowlist secret
+          },
+        },
+      },
+    };
+
+    const account = resolveFeishuAccount({ cfg: cfg as never, accountId: undefined });
+    expectExplicitDefaultAccountSelection(account, "cli_router");
+  });
+
+  it("keeps explicit accountId selection", () => {
+    const cfg = {
+      channels: {
+        feishu: {
+          defaultAccount: "router-d",
+          accounts: makeDefaultAndRouterAccounts(),
+        },
+      },
+    };
+
+    const account = resolveFeishuAccount({ cfg: cfg as never, accountId: "default" });
+    expect(account.accountId).toBe("default");
+    expect(account.selectionSource).toBe("explicit");
+    expect(account.appId).toBe("cli_default");
+  });
+
+  it("treats unresolved SecretRef as not configured in account resolution", () => {
+    const account = resolveFeishuAccount({
+      cfg: {
+        channels: {
+          feishu: {
+            accounts: {
+              main: {
+                appId: "cli_123",
+                appSecret: { source: "file", provider: "default", id: "path/to/secret" },
+              } as never,
+            },
+          },
+        },
+      } as never,
+      accountId: "main",
+    });
+    expect(account.configured).toBe(false);
+    expect(account.appSecret).toBeUndefined();
+  });
+
+  it("keeps account configured when optional event SecretRefs are unresolved in inspect mode", () => {
+    const account = resolveFeishuAccount({
+      cfg: {
+        channels: {
+          feishu: {
+            accounts: {
+              main: {
+                appId: "cli_123",
+                appSecret: "secret_456",
+                verificationToken: {
+                  source: "file",
+                  provider: "default",
+                  id: "path/to/token",
+                },
+              } as never,
+            },
+          },
+        },
+      } as never,
+      accountId: "main",
+    });
+
+    expect(account.configured).toBe(true);
+    expect(account.appSecret).toBe("secret_456");
+    expect(account.verificationToken).toBeUndefined();
+  });
+
+  it("throws typed SecretRef errors in runtime account resolution", () => {
+    let caught: unknown;
+    try {
+      resolveFeishuRuntimeAccount({
+        cfg: {
+          channels: {
+            feishu: {
+              accounts: {
+                main: {
+                  appId: "cli_123",
+                  appSecret: { source: "file", provider: "default", id: "path/to/secret" },
+                } as never,
+              },
+            },
+          },
+        } as never,
+        accountId: "main",
+      });
+    } catch (error) {
+      caught = error;
+    }
+
+    expect(caught).toBeInstanceOf(FeishuSecretRefUnavailableError);
+    expect((caught as Error).message).toMatch(/channels\.feishu\.appSecret: unresolved SecretRef/i);
+  });
+
+  it("ignores non-string account names", () => {
+    const account = resolveFeishuAccount({
+      cfg: {
+        channels: {
+          feishu: {
+            accounts: {
+              main: {
+                name: { bad: true },
+                appId: "cli_123",
+                appSecret: "secret_456", // pragma: allowlist secret
+              } as never,
+            },
+          },
+        },
+      } as never,
+      accountId: "main",
+    });
+
+    expect(account.accountId).toBe("main");
+    expect(account.appId).toBe("cli_123");
+    expect(account.appSecret).toBe("secret_456");
+    expect(account.name).toBeUndefined();
+  });
+});