@nextclaw/channel-plugin-feishu 0.2.13 → 0.2.15

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

@@ -0,0 +1,142 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  createFeishuClientMockModule,
+  createFeishuRuntimeMockModule,
+} from "./monitor.test-mocks.js";
+import {
+  buildWebhookConfig,
+  getFreePort,
+  withRunningWebhookMonitor,
+} from "./monitor.webhook.test-helpers.js";
+
+const probeFeishuMock = vi.hoisted(() => vi.fn());
+
+vi.mock("./probe.js", () => ({
+  probeFeishu: probeFeishuMock,
+}));
+
+vi.mock("./client.js", () => createFeishuClientMockModule());
+vi.mock("./runtime.js", () => createFeishuRuntimeMockModule());
+
+vi.mock("@larksuiteoapi/node-sdk", () => ({
+  adaptDefault: vi.fn(
+    () => (_req: unknown, res: { statusCode?: number; end: (s: string) => void }) => {
+      res.statusCode = 200;
+      res.end("ok");
+    },
+  ),
+}));
+
+import {
+  clearFeishuWebhookRateLimitStateForTest,
+  getFeishuWebhookRateLimitStateSizeForTest,
+  isWebhookRateLimitedForTest,
+  monitorFeishuProvider,
+  stopFeishuMonitor,
+} from "./monitor.js";
+
+afterEach(() => {
+  clearFeishuWebhookRateLimitStateForTest();
+  stopFeishuMonitor();
+});
+
+describe("Feishu webhook security hardening", () => {
+  it("rejects webhook mode without verificationToken", async () => {
+    probeFeishuMock.mockResolvedValue({ ok: true, botOpenId: "bot_open_id" });
+
+    const cfg = buildWebhookConfig({
+      accountId: "missing-token",
+      path: "/hook-missing-token",
+      port: await getFreePort(),
+    });
+
+    await expect(monitorFeishuProvider({ config: cfg })).rejects.toThrow(
+      /requires verificationToken/i,
+    );
+  });
+
+  it("rejects webhook mode without encryptKey", async () => {
+    probeFeishuMock.mockResolvedValue({ ok: true, botOpenId: "bot_open_id" });
+
+    const cfg = buildWebhookConfig({
+      accountId: "missing-encrypt-key",
+      path: "/hook-missing-encrypt",
+      port: await getFreePort(),
+      verificationToken: "verify_token",
+    });
+
+    await expect(monitorFeishuProvider({ config: cfg })).rejects.toThrow(/requires encryptKey/i);
+  });
+
+  it("returns 415 for POST requests without json content type", async () => {
+    probeFeishuMock.mockResolvedValue({ ok: true, botOpenId: "bot_open_id" });
+    await withRunningWebhookMonitor(
+      {
+        accountId: "content-type",
+        path: "/hook-content-type",
+        verificationToken: "verify_token",
+        encryptKey: "encrypt_key",
+      },
+      monitorFeishuProvider,
+      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" });
+    await withRunningWebhookMonitor(
+      {
+        accountId: "rate-limit",
+        path: "/hook-rate-limit",
+        verificationToken: "verify_token",
+        encryptKey: "encrypt_key",
+      },
+      monitorFeishuProvider,
+      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);
+      },
+    );
+  });
+
+  it("caps tracked webhook rate-limit keys to prevent unbounded growth", () => {
+    const now = 1_000_000;
+    for (let i = 0; i < 4_500; i += 1) {
+      isWebhookRateLimitedForTest(`/feishu-rate-limit:key-${i}`, now);
+    }
+    expect(getFeishuWebhookRateLimitStateSizeForTest()).toBeLessThanOrEqual(4_096);
+  });
+
+  it("prunes stale webhook rate-limit state after window elapses", () => {
+    const now = 2_000_000;
+    for (let i = 0; i < 100; i += 1) {
+      isWebhookRateLimitedForTest(`/feishu-rate-limit-stale:key-${i}`, now);
+    }
+    expect(getFeishuWebhookRateLimitStateSizeForTest()).toBe(100);
+
+    isWebhookRateLimitedForTest("/feishu-rate-limit-stale:fresh", now + 60_001);
+    expect(getFeishuWebhookRateLimitStateSizeForTest()).toBe(1);
+  });
+});

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

@@ -0,0 +1,98 @@
+import { createServer } from "node:http";
+import type { AddressInfo } from "node:net";
+import type { ClawdbotConfig } from "./nextclaw-sdk/feishu.js";
+import { vi } from "vitest";
+import type { monitorFeishuProvider } from "./monitor.js";
+
+export async function getFreePort(): Promise<number> {
+  const server = createServer();
+  await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", () => resolve()));
+  const address = server.address() as AddressInfo | null;
+  if (!address) {
+    throw new Error("missing server address");
+  }
+  await new Promise<void>((resolve) => server.close(() => resolve()));
+  return address.port;
+}
+
+async function waitUntilServerReady(url: string): Promise<void> {
+  for (let i = 0; i < 50; i += 1) {
+    try {
+      const response = await fetch(url, { method: "GET" });
+      if (response.status >= 200 && response.status < 500) {
+        return;
+      }
+    } catch {
+      // retry
+    }
+    await new Promise((resolve) => setTimeout(resolve, 20));
+  }
+  throw new Error(`server did not start: ${url}`);
+}
+
+export function buildWebhookConfig(params: {
+  accountId: string;
+  path: string;
+  port: number;
+  verificationToken?: string;
+  encryptKey?: string;
+}): ClawdbotConfig {
+  return {
+    channels: {
+      feishu: {
+        enabled: true,
+        accounts: {
+          [params.accountId]: {
+            enabled: true,
+            appId: "cli_test",
+            appSecret: "secret_test", // pragma: allowlist secret
+            connectionMode: "webhook",
+            webhookHost: "127.0.0.1",
+            webhookPort: params.port,
+            webhookPath: params.path,
+            encryptKey: params.encryptKey,
+            verificationToken: params.verificationToken,
+          },
+        },
+      },
+    },
+  } as ClawdbotConfig;
+}
+
+export async function withRunningWebhookMonitor(
+  params: {
+    accountId: string;
+    path: string;
+    verificationToken: string;
+    encryptKey: string;
+  },
+  monitor: typeof monitorFeishuProvider,
+  run: (url: string) => Promise<void>,
+) {
+  const port = await getFreePort();
+  const cfg = buildWebhookConfig({
+    accountId: params.accountId,
+    path: params.path,
+    port,
+    encryptKey: params.encryptKey,
+    verificationToken: params.verificationToken,
+  });
+
+  const abortController = new AbortController();
+  const runtime = { log: vi.fn(), error: vi.fn(), exit: vi.fn() };
+  const monitorPromise = monitor({
+    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;
+  }
+}

package/src/nextclaw-sdk/account-id.ts

@@ -0,0 +1,31 @@
+export const DEFAULT_ACCOUNT_ID = "default";
+
+export function normalizeAccountId(accountId?: string | null): string {
+  const trimmed = accountId?.trim();
+  return trimmed || DEFAULT_ACCOUNT_ID;
+}
+
+export function normalizeOptionalAccountId(accountId?: string | null): string | undefined {
+  const trimmed = accountId?.trim();
+  return trimmed ? normalizeAccountId(trimmed) : undefined;
+}
+
+const VALID_AGENT_ID_RE = /^[a-z0-9][a-z0-9_-]{0,63}$/i;
+const INVALID_AGENT_CHARS_RE = /[^a-z0-9_-]+/g;
+
+export function normalizeAgentId(value?: string | null): string {
+  const trimmed = value?.trim();
+  if (!trimmed) {
+    return "main";
+  }
+  if (VALID_AGENT_ID_RE.test(trimmed)) {
+    return trimmed.toLowerCase();
+  }
+  const normalized = trimmed
+    .toLowerCase()
+    .replace(INVALID_AGENT_CHARS_RE, "-")
+    .replace(/^-+/, "")
+    .replace(/-+$/, "")
+    .slice(0, 64);
+  return normalized || "main";
+}

package/src/nextclaw-sdk/compat.ts

@@ -0,0 +1,8 @@
+export {
+  collectAllowlistProviderRestrictSendersWarnings,
+  formatAllowFromLowercase,
+  listDirectoryGroupEntriesFromMapKeysAndAllowFrom,
+  listDirectoryUserEntriesFromAllowFromAndMapKeys,
+  mapAllowFromEntries,
+} from "./core.js";
+export { createPluginRuntimeStore } from "./runtime-store.js";

package/src/nextclaw-sdk/core-channel.ts

@@ -0,0 +1,296 @@
+import type { GroupPolicy, OpenClawConfig } from "./types.js";
+
+export function emptyPluginConfigSchema(): {
+  type: "object";
+  additionalProperties: false;
+  properties: Record<string, unknown>;
+} {
+  return {
+    type: "object",
+    additionalProperties: false,
+    properties: {},
+  };
+}
+
+const warnedMissingProviderGroupPolicy = new Set<string>();
+
+export function resolveDefaultGroupPolicy(cfg: {
+  channels?: {
+    defaults?: {
+      groupPolicy?: GroupPolicy;
+    };
+  };
+}): GroupPolicy | undefined {
+  return cfg.channels?.defaults?.groupPolicy;
+}
+
+export function resolveOpenProviderRuntimeGroupPolicy(params: {
+  providerConfigPresent: boolean;
+  groupPolicy?: GroupPolicy;
+  defaultGroupPolicy?: GroupPolicy;
+}): {
+  groupPolicy: GroupPolicy;
+  providerMissingFallbackApplied: boolean;
+} {
+  const groupPolicy = params.providerConfigPresent
+    ? (params.groupPolicy ?? params.defaultGroupPolicy ?? "open")
+    : (params.groupPolicy ?? "allowlist");
+  return {
+    groupPolicy,
+    providerMissingFallbackApplied: !params.providerConfigPresent && params.groupPolicy === undefined,
+  };
+}
+
+export function warnMissingProviderGroupPolicyFallbackOnce(params: {
+  providerMissingFallbackApplied: boolean;
+  providerKey: string;
+  accountId?: string;
+  blockedLabel?: string;
+  log: (message: string) => void;
+}): boolean {
+  if (!params.providerMissingFallbackApplied) {
+    return false;
+  }
+  const key = `${params.providerKey}:${params.accountId ?? "*"}`;
+  if (warnedMissingProviderGroupPolicy.has(key)) {
+    return false;
+  }
+  warnedMissingProviderGroupPolicy.add(key);
+  const blockedLabel = params.blockedLabel?.trim() || "group messages";
+  params.log(
+    `${params.providerKey}: channels.${params.providerKey} is missing; defaulting groupPolicy to "allowlist" (${blockedLabel} blocked until explicitly configured).`,
+  );
+  return true;
+}
+
+export function evaluateSenderGroupAccessForPolicy(params: {
+  groupPolicy: GroupPolicy;
+  providerMissingFallbackApplied?: boolean;
+  groupAllowFrom: string[];
+  senderId: string;
+  isSenderAllowed: (senderId: string, allowFrom: string[]) => boolean;
+}): {
+  allowed: boolean;
+  groupPolicy: GroupPolicy;
+  providerMissingFallbackApplied: boolean;
+  reason: "allowed" | "disabled" | "empty_allowlist" | "sender_not_allowlisted";
+} {
+  if (params.groupPolicy === "disabled") {
+    return {
+      allowed: false,
+      groupPolicy: params.groupPolicy,
+      providerMissingFallbackApplied: Boolean(params.providerMissingFallbackApplied),
+      reason: "disabled",
+    };
+  }
+  if (params.groupPolicy === "allowlist") {
+    if (params.groupAllowFrom.length === 0) {
+      return {
+        allowed: false,
+        groupPolicy: params.groupPolicy,
+        providerMissingFallbackApplied: Boolean(params.providerMissingFallbackApplied),
+        reason: "empty_allowlist",
+      };
+    }
+    if (!params.isSenderAllowed(params.senderId, params.groupAllowFrom)) {
+      return {
+        allowed: false,
+        groupPolicy: params.groupPolicy,
+        providerMissingFallbackApplied: Boolean(params.providerMissingFallbackApplied),
+        reason: "sender_not_allowlisted",
+      };
+    }
+  }
+  return {
+    allowed: true,
+    groupPolicy: params.groupPolicy,
+    providerMissingFallbackApplied: Boolean(params.providerMissingFallbackApplied),
+    reason: "allowed",
+  };
+}
+
+export function createDefaultChannelRuntimeState<T extends Record<string, unknown>>(
+  accountId: string,
+  extra?: T,
+): {
+  accountId: string;
+  running: false;
+  lastStartAt: null;
+  lastStopAt: null;
+  lastError: null;
+} & T {
+  return {
+    accountId,
+    running: false,
+    lastStartAt: null,
+    lastStopAt: null,
+    lastError: null,
+    ...(extra ?? ({} as T)),
+  };
+}
+
+export function buildProbeChannelStatusSummary<TExtra extends Record<string, unknown>>(
+  snapshot: {
+    configured?: boolean | null;
+    running?: boolean | null;
+    lastStartAt?: number | null;
+    lastStopAt?: number | null;
+    lastError?: string | null;
+    probe?: unknown;
+    lastProbeAt?: number | null;
+  },
+  extra?: TExtra,
+) {
+  return {
+    configured: snapshot.configured ?? false,
+    running: snapshot.running ?? false,
+    lastStartAt: snapshot.lastStartAt ?? null,
+    lastStopAt: snapshot.lastStopAt ?? null,
+    lastError: snapshot.lastError ?? null,
+    ...(extra ?? ({} as TExtra)),
+    probe: snapshot.probe,
+    lastProbeAt: snapshot.lastProbeAt ?? null,
+  };
+}
+
+export function buildRuntimeAccountStatusSnapshot(params: {
+  runtime?: {
+    running?: boolean | null;
+    lastStartAt?: number | null;
+    lastStopAt?: number | null;
+    lastError?: string | null;
+  } | null;
+  probe?: unknown;
+}) {
+  return {
+    running: params.runtime?.running ?? false,
+    lastStartAt: params.runtime?.lastStartAt ?? null,
+    lastStopAt: params.runtime?.lastStopAt ?? null,
+    lastError: params.runtime?.lastError ?? null,
+    probe: params.probe,
+  };
+}
+
+export function mapAllowFromEntries(
+  allowFrom: Array<string | number> | null | undefined,
+): string[] {
+  return (allowFrom ?? []).map((entry) => String(entry));
+}
+
+export function formatAllowFromLowercase(params: {
+  allowFrom: Array<string | number>;
+  stripPrefixRe?: RegExp;
+}): string[] {
+  return params.allowFrom
+    .map((entry) => String(entry).trim())
+    .filter(Boolean)
+    .map((entry) => (params.stripPrefixRe ? entry.replace(params.stripPrefixRe, "") : entry))
+    .map((entry) => entry.toLowerCase());
+}
+
+function applyDirectoryQueryAndLimit(
+  ids: string[],
+  params: { query?: string | null; limit?: number | null },
+): string[] {
+  const query = params.query?.trim().toLowerCase() || "";
+  const limit = typeof params.limit === "number" && params.limit > 0 ? params.limit : undefined;
+  const filtered = ids.filter((id) => (query ? id.toLowerCase().includes(query) : true));
+  return typeof limit === "number" ? filtered.slice(0, limit) : filtered;
+}
+
+function dedupeIds(ids: string[]): string[] {
+  return Array.from(new Set(ids));
+}
+
+function collectEntryIds(params: {
+  entries?: readonly unknown[];
+  normalizeId?: (entry: string) => string | null | undefined;
+}): string[] {
+  return (params.entries ?? [])
+    .map((entry) => String(entry).trim())
+    .filter((entry) => Boolean(entry) && entry !== "*")
+    .map((entry) => {
+      const normalized = params.normalizeId ? params.normalizeId(entry) : entry;
+      return typeof normalized === "string" ? normalized.trim() : "";
+    })
+    .filter(Boolean);
+}
+
+function collectMapIds(params: {
+  map?: Record<string, unknown>;
+  normalizeId?: (entry: string) => string | null | undefined;
+}): string[] {
+  return collectEntryIds({
+    entries: Object.keys(params.map ?? {}),
+    normalizeId: params.normalizeId,
+  });
+}
+
+export function listDirectoryUserEntriesFromAllowFromAndMapKeys(params: {
+  allowFrom?: readonly unknown[];
+  map?: Record<string, unknown>;
+  query?: string | null;
+  limit?: number | null;
+  normalizeAllowFromId?: (entry: string) => string | null | undefined;
+  normalizeMapKeyId?: (entry: string) => string | null | undefined;
+}): Array<{ kind: "user"; id: string }> {
+  const ids = dedupeIds([
+    ...collectEntryIds({
+      entries: params.allowFrom,
+      normalizeId: params.normalizeAllowFromId,
+    }),
+    ...collectMapIds({
+      map: params.map,
+      normalizeId: params.normalizeMapKeyId,
+    }),
+  ]);
+  return applyDirectoryQueryAndLimit(ids, params).map((id) => ({ kind: "user", id }));
+}
+
+export function listDirectoryGroupEntriesFromMapKeysAndAllowFrom(params: {
+  groups?: Record<string, unknown>;
+  allowFrom?: readonly unknown[];
+  query?: string | null;
+  limit?: number | null;
+  normalizeMapKeyId?: (entry: string) => string | null | undefined;
+  normalizeAllowFromId?: (entry: string) => string | null | undefined;
+}): Array<{ kind: "group"; id: string }> {
+  const ids = dedupeIds([
+    ...collectMapIds({
+      map: params.groups,
+      normalizeId: params.normalizeMapKeyId,
+    }),
+    ...collectEntryIds({
+      entries: params.allowFrom,
+      normalizeId: params.normalizeAllowFromId,
+    }),
+  ]);
+  return applyDirectoryQueryAndLimit(ids, params).map((id) => ({ kind: "group", id }));
+}
+
+export function collectAllowlistProviderRestrictSendersWarnings(params: {
+  cfg: OpenClawConfig;
+  providerConfigPresent: boolean;
+  configuredGroupPolicy?: GroupPolicy | null;
+  surface: string;
+  openScope: string;
+  groupPolicyPath: string;
+  groupAllowFromPath: string;
+  mentionGated?: boolean;
+}): string[] {
+  const defaultGroupPolicy = resolveDefaultGroupPolicy(params.cfg as {
+    channels?: { defaults?: { groupPolicy?: GroupPolicy } };
+  });
+  const { groupPolicy } = resolveOpenProviderRuntimeGroupPolicy({
+    providerConfigPresent: params.providerConfigPresent,
+    groupPolicy: params.configuredGroupPolicy ?? undefined,
+    defaultGroupPolicy,
+  });
+  if (groupPolicy !== "open") {
+    return [];
+  }
+  const mentionSuffix = params.mentionGated === false ? "" : " (mention-gated)";
+  return [
+    `- ${params.surface}: groupPolicy="open" allows ${params.openScope} to trigger${mentionSuffix}. Set ${params.groupPolicyPath}="allowlist" + ${params.groupAllowFromPath} to restrict senders.`,
+  ];
+}