@openclaw/discord 2026.3.13 → 2026.5.1-beta.1

package/src/security-audit.test.ts

@@ -0,0 +1,246 @@
+import { describe, expect, it, vi } from "vitest";
+import type { ResolvedDiscordAccount } from "./accounts.js";
+import type { OpenClawConfig } from "./runtime-api.js";
+import { collectDiscordSecurityAuditFindings } from "./security-audit.js";
+
+type DiscordAccountConfig = ResolvedDiscordAccount["config"];
+
+const { readChannelAllowFromStoreMock } = vi.hoisted(() => ({
+  readChannelAllowFromStoreMock: vi.fn(async () => [] as string[]),
+}));
+
+vi.mock("openclaw/plugin-sdk/conversation-runtime", () => ({
+  readChannelAllowFromStore: readChannelAllowFromStoreMock,
+}));
+
+function createAccount(
+  config: DiscordAccountConfig,
+  accountId = "default",
+): ResolvedDiscordAccount {
+  return {
+    accountId,
+    enabled: true,
+    token: "t",
+    tokenSource: "config",
+    config,
+  };
+}
+
+async function collectFindings(params: {
+  cfg: OpenClawConfig;
+  config: DiscordAccountConfig;
+  accountId?: string;
+  orderedAccountIds?: string[];
+  hasExplicitAccountPath?: boolean;
+  storeAllowFrom?: string[];
+}) {
+  readChannelAllowFromStoreMock.mockResolvedValue(params.storeAllowFrom ?? []);
+  return await collectDiscordSecurityAuditFindings({
+    cfg: params.cfg,
+    account: createAccount(params.config, params.accountId),
+    accountId: params.accountId ?? "default",
+    orderedAccountIds: params.orderedAccountIds ?? ["default"],
+    hasExplicitAccountPath: params.hasExplicitAccountPath ?? false,
+  });
+}
+
+describe("Discord security audit findings", () => {
+  it("flags slash commands when access-group enforcement is disabled and no users allowlist exists", async () => {
+    const cfg: OpenClawConfig = {
+      commands: { native: true, useAccessGroups: false },
+      channels: {
+        discord: {
+          enabled: true,
+          token: "t",
+          groupPolicy: "allowlist",
+          guilds: {
+            "123": {
+              channels: {
+                general: { enabled: true },
+              },
+            },
+          },
+        },
+      },
+    };
+
+    const discordConfig = cfg.channels?.discord;
+    if (!discordConfig) {
+      throw new Error("discord config required");
+    }
+    const findings = await collectFindings({
+      cfg,
+      config: discordConfig,
+    });
+
+    expect(findings).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          checkId: "channels.discord.commands.native.unrestricted",
+          severity: "critical",
+        }),
+      ]),
+    );
+  });
+
+  it.each([
+    {
+      name: "flags missing guild user allowlists",
+      cfg: {
+        commands: { native: true },
+        channels: {
+          discord: {
+            enabled: true,
+            token: "t",
+            groupPolicy: "allowlist",
+            guilds: {
+              "123": {
+                channels: {
+                  general: { enabled: true },
+                },
+              },
+            },
+          },
+        },
+      } satisfies OpenClawConfig,
+      expectFinding: true,
+    },
+    {
+      name: "does not flag when dm.allowFrom includes a Discord snowflake id",
+      cfg: {
+        commands: { native: true },
+        channels: {
+          discord: {
+            enabled: true,
+            token: "t",
+            dm: { allowFrom: ["387380367612706819"] },
+            groupPolicy: "allowlist",
+            guilds: {
+              "123": {
+                channels: {
+                  general: { enabled: true },
+                },
+              },
+            },
+          },
+        },
+      } satisfies OpenClawConfig,
+      expectFinding: false,
+    },
+  ])("$name", async (testCase) => {
+    const findings = await collectFindings({
+      cfg: testCase.cfg,
+      config: testCase.cfg.channels.discord,
+    });
+
+    expect(
+      findings.some(
+        (finding) => finding.checkId === "channels.discord.commands.native.no_allowlists",
+      ),
+    ).toBe(testCase.expectFinding);
+  });
+
+  it.each([
+    {
+      name: "warns when Discord allowlists contain name-based entries",
+      config: {
+        enabled: true,
+        token: "t",
+        allowFrom: ["Alice#1234", "<@123456789012345678>"],
+        guilds: {
+          "123": {
+            users: ["trusted.operator"],
+            channels: {
+              general: {
+                users: ["987654321098765432", "security-team"],
+              },
+            },
+          },
+        },
+      } satisfies DiscordAccountConfig,
+      storeAllowFrom: ["team.owner"],
+      expectNameBasedSeverity: "warn",
+      detailIncludes: [
+        "channels.discord.allowFrom:Alice#1234",
+        "channels.discord.guilds.123.users:trusted.operator",
+        "channels.discord.guilds.123.channels.general.users:security-team",
+        "~/.openclaw/credentials/discord-allowFrom.json:team.owner",
+      ],
+      detailExcludes: ["<@123456789012345678>"],
+    },
+    {
+      name: "marks Discord name-based allowlists as break-glass when dangerous matching is enabled",
+      config: {
+        enabled: true,
+        token: "t",
+        dangerouslyAllowNameMatching: true,
+        allowFrom: ["Alice#1234"],
+      } satisfies DiscordAccountConfig,
+      expectNameBasedSeverity: "info",
+      detailIncludes: ["out-of-scope"],
+    },
+    {
+      name: "audits name-based allowlists on non-default Discord accounts",
+      accountId: "beta",
+      orderedAccountIds: ["alpha", "beta"],
+      hasExplicitAccountPath: true,
+      config: {
+        enabled: true,
+        token: "b",
+        allowFrom: ["Alice#1234"],
+      } satisfies DiscordAccountConfig,
+      expectNameBasedSeverity: "warn",
+      detailIncludes: ["channels.discord.accounts.beta.allowFrom:Alice#1234"],
+    },
+    {
+      name: "does not warn when Discord allowlists use ID-style entries only",
+      config: {
+        enabled: true,
+        token: "t",
+        allowFrom: [
+          "123456789012345678",
+          "<@223456789012345678>",
+          "user:323456789012345678",
+          "discord:423456789012345678",
+          "pk:member-123",
+        ],
+        guilds: {
+          "123": {
+            users: ["523456789012345678", "<@623456789012345678>", "pk:member-456"],
+            channels: {
+              general: {
+                users: ["723456789012345678", "user:823456789012345678"],
+              },
+            },
+          },
+        },
+      } satisfies DiscordAccountConfig,
+      expectNoNameBasedFinding: true,
+    },
+  ])("$name", async (testCase) => {
+    const findings = await collectFindings({
+      cfg: { channels: { discord: testCase.config } },
+      config: testCase.config,
+      accountId: testCase.accountId,
+      orderedAccountIds: testCase.orderedAccountIds,
+      hasExplicitAccountPath: testCase.hasExplicitAccountPath,
+      storeAllowFrom: testCase.storeAllowFrom,
+    });
+    const nameBasedFinding = findings.find(
+      (entry) => entry.checkId === "channels.discord.allowFrom.name_based_entries",
+    );
+
+    if (testCase.expectNoNameBasedFinding) {
+      expect(nameBasedFinding).toBeUndefined();
+    } else {
+      expect(nameBasedFinding).toBeDefined();
+      expect(nameBasedFinding?.severity).toBe(testCase.expectNameBasedSeverity);
+      for (const snippet of testCase.detailIncludes ?? []) {
+        expect(nameBasedFinding?.detail).toContain(snippet);
+      }
+      for (const snippet of testCase.detailExcludes ?? []) {
+        expect(nameBasedFinding?.detail).not.toContain(snippet);
+      }
+    }
+  });
+});

package/src/security-audit.ts

@@ -0,0 +1,208 @@
+import { coerceNativeSetting, normalizeAllowFromList } from "openclaw/plugin-sdk/channel-policy";
+import { readChannelAllowFromStore } from "openclaw/plugin-sdk/conversation-runtime";
+import { isDangerousNameMatchingEnabled } from "openclaw/plugin-sdk/dangerous-name-runtime";
+import {
+  resolveNativeCommandsEnabled,
+  resolveNativeSkillsEnabled,
+} from "openclaw/plugin-sdk/native-command-config-runtime";
+import type { ResolvedDiscordAccount } from "./accounts.js";
+import type { OpenClawConfig } from "./runtime-api.js";
+import { isDiscordMutableAllowEntry } from "./security-doctor.js";
+
+function normalizeOptionalString(value: string | null | undefined): string | undefined {
+  const normalized = value?.trim();
+  return normalized ? normalized : undefined;
+}
+
+function addDiscordNameBasedEntries(params: {
+  target: Set<string>;
+  values: unknown;
+  source: string;
+}) {
+  if (!Array.isArray(params.values)) {
+    return;
+  }
+  for (const value of params.values) {
+    if (!isDiscordMutableAllowEntry(String(value))) {
+      continue;
+    }
+    const text = normalizeOptionalString(String(value)) ?? "";
+    if (!text) {
+      continue;
+    }
+    params.target.add(`${params.source}:${text}`);
+  }
+}
+
+export async function collectDiscordSecurityAuditFindings(params: {
+  cfg: OpenClawConfig;
+  accountId?: string | null;
+  account: ResolvedDiscordAccount;
+  orderedAccountIds: string[];
+  hasExplicitAccountPath: boolean;
+}) {
+  const findings: Array<{
+    checkId: string;
+    severity: "info" | "warn" | "critical";
+    title: string;
+    detail: string;
+    remediation?: string;
+  }> = [];
+  const discordCfg = params.account.config ?? {};
+  const accountId =
+    normalizeOptionalString(params.accountId) ?? params.account.accountId ?? "default";
+  const dangerousNameMatchingEnabled = isDangerousNameMatchingEnabled(discordCfg);
+  const storeAllowFrom = await readChannelAllowFromStore("discord", process.env, accountId).catch(
+    () => [],
+  );
+  const discordNameBasedAllowEntries = new Set<string>();
+  const discordPathPrefix =
+    params.orderedAccountIds.length > 1 || params.hasExplicitAccountPath
+      ? `channels.discord.accounts.${accountId}`
+      : "channels.discord";
+
+  addDiscordNameBasedEntries({
+    target: discordNameBasedAllowEntries,
+    values: discordCfg.allowFrom,
+    source: `${discordPathPrefix}.allowFrom`,
+  });
+  addDiscordNameBasedEntries({
+    target: discordNameBasedAllowEntries,
+    values: (discordCfg.dm as { allowFrom?: unknown } | undefined)?.allowFrom,
+    source: `${discordPathPrefix}.dm.allowFrom`,
+  });
+  addDiscordNameBasedEntries({
+    target: discordNameBasedAllowEntries,
+    values: storeAllowFrom,
+    source: "~/.openclaw/credentials/discord-allowFrom.json",
+  });
+
+  const guildEntries = (discordCfg.guilds as Record<string, unknown> | undefined) ?? {};
+  for (const [guildKey, guildValue] of Object.entries(guildEntries)) {
+    if (!guildValue || typeof guildValue !== "object") {
+      continue;
+    }
+    const guild = guildValue as Record<string, unknown>;
+    addDiscordNameBasedEntries({
+      target: discordNameBasedAllowEntries,
+      values: guild.users,
+      source: `${discordPathPrefix}.guilds.${guildKey}.users`,
+    });
+    const channels = guild.channels;
+    if (!channels || typeof channels !== "object") {
+      continue;
+    }
+    for (const [channelKey, channelValue] of Object.entries(channels as Record<string, unknown>)) {
+      if (!channelValue || typeof channelValue !== "object") {
+        continue;
+      }
+      const channel = channelValue as Record<string, unknown>;
+      addDiscordNameBasedEntries({
+        target: discordNameBasedAllowEntries,
+        values: channel.users,
+        source: `${discordPathPrefix}.guilds.${guildKey}.channels.${channelKey}.users`,
+      });
+    }
+  }
+
+  if (discordNameBasedAllowEntries.size > 0) {
+    const examples = Array.from(discordNameBasedAllowEntries).slice(0, 5);
+    const more =
+      discordNameBasedAllowEntries.size > examples.length
+        ? ` (+${discordNameBasedAllowEntries.size - examples.length} more)`
+        : "";
+    findings.push({
+      checkId: "channels.discord.allowFrom.name_based_entries",
+      severity: dangerousNameMatchingEnabled ? "info" : "warn",
+      title: dangerousNameMatchingEnabled
+        ? "Discord allowlist uses break-glass name/tag matching"
+        : "Discord allowlist contains name or tag entries",
+      detail: dangerousNameMatchingEnabled
+        ? "Discord name/tag allowlist matching is explicitly enabled via dangerouslyAllowNameMatching. This mutable-identity mode is operator-selected break-glass behavior and out-of-scope for vulnerability reports by itself. " +
+          `Found: ${examples.join(", ")}${more}.`
+        : "Discord name/tag allowlist matching uses normalized slugs and can collide across users. " +
+          `Found: ${examples.join(", ")}${more}.`,
+      remediation: dangerousNameMatchingEnabled
+        ? "Prefer stable Discord IDs (or <@id>/user:<id>/pk:<id>), then disable dangerouslyAllowNameMatching."
+        : "Prefer stable Discord IDs (or <@id>/user:<id>/pk:<id>) in channels.discord.allowFrom and channels.discord.guilds.*.users, or explicitly opt in with dangerouslyAllowNameMatching=true if you accept the risk.",
+    });
+  }
+
+  const nativeEnabled = resolveNativeCommandsEnabled({
+    providerId: "discord",
+    providerSetting: coerceNativeSetting(
+      (discordCfg.commands as { native?: unknown } | undefined)?.native,
+    ),
+    globalSetting: params.cfg.commands?.native,
+  });
+  const nativeSkillsEnabled = resolveNativeSkillsEnabled({
+    providerId: "discord",
+    providerSetting: coerceNativeSetting(
+      (discordCfg.commands as { nativeSkills?: unknown } | undefined)?.nativeSkills,
+    ),
+    globalSetting: params.cfg.commands?.nativeSkills,
+  });
+  if (!nativeEnabled && !nativeSkillsEnabled) {
+    return findings;
+  }
+
+  const defaultGroupPolicy = params.cfg.channels?.defaults?.groupPolicy;
+  const groupPolicy =
+    (discordCfg.groupPolicy as string | undefined) ?? defaultGroupPolicy ?? "allowlist";
+  const guildsConfigured = Object.keys(guildEntries).length > 0;
+  const hasAnyUserAllowlist = Object.values(guildEntries).some((guild) => {
+    if (!guild || typeof guild !== "object") {
+      return false;
+    }
+    const record = guild as Record<string, unknown>;
+    if (Array.isArray(record.users) && record.users.length > 0) {
+      return true;
+    }
+    const channels = record.channels;
+    if (!channels || typeof channels !== "object") {
+      return false;
+    }
+    return Object.values(channels as Record<string, unknown>).some((channel) => {
+      if (!channel || typeof channel !== "object") {
+        return false;
+      }
+      const channelRecord = channel as Record<string, unknown>;
+      return Array.isArray(channelRecord.users) && channelRecord.users.length > 0;
+    });
+  });
+  const dmAllowFromRaw = (discordCfg.dm as { allowFrom?: unknown } | undefined)?.allowFrom;
+  const dmAllowFrom = Array.isArray(dmAllowFromRaw) ? dmAllowFromRaw : [];
+  const ownerAllowFromConfigured =
+    normalizeAllowFromList([...dmAllowFrom, ...storeAllowFrom]).length > 0;
+  const useAccessGroups = params.cfg.commands?.useAccessGroups !== false;
+
+  if (!useAccessGroups && groupPolicy !== "disabled" && guildsConfigured && !hasAnyUserAllowlist) {
+    findings.push({
+      checkId: "channels.discord.commands.native.unrestricted",
+      severity: "critical",
+      title: "Discord slash commands are unrestricted",
+      detail:
+        "commands.useAccessGroups=false disables sender allowlists for Discord slash commands unless a per-guild/channel users allowlist is configured; with no users allowlist, any user in allowed guild channels can invoke /… commands.",
+      remediation:
+        "Set commands.useAccessGroups=true (recommended), or configure channels.discord.guilds.<id>.users (or channels.discord.guilds.<id>.channels.<channel>.users).",
+    });
+  } else if (
+    useAccessGroups &&
+    groupPolicy !== "disabled" &&
+    guildsConfigured &&
+    !ownerAllowFromConfigured &&
+    !hasAnyUserAllowlist
+  ) {
+    findings.push({
+      checkId: "channels.discord.commands.native.no_allowlists",
+      severity: "warn",
+      title: "Discord slash commands have no allowlists",
+      detail:
+        "Discord slash commands are enabled, but neither an owner allowFrom list nor any per-guild/channel users allowlist is configured; /… commands will be rejected for everyone.",
+      remediation:
+        "Add your user id to channels.discord.allowFrom (or approve yourself via pairing), or configure channels.discord.guilds.<id>.users.",
+    });
+  }
+
+  return findings;
+}

package/src/security-contract.ts

@@ -0,0 +1,47 @@
+import { isRecord } from "openclaw/plugin-sdk/text-runtime";
+
+type UnsupportedSecretRefConfigCandidate = {
+  path: string;
+  value: unknown;
+};
+
+export const unsupportedSecretRefSurfacePatterns = [
+  "channels.discord.threadBindings.webhookToken",
+  "channels.discord.accounts.*.threadBindings.webhookToken",
+] as const;
+
+export function collectUnsupportedSecretRefConfigCandidates(
+  raw: unknown,
+): UnsupportedSecretRefConfigCandidate[] {
+  if (!isRecord(raw)) {
+    return [];
+  }
+  if (!isRecord(raw.channels) || !isRecord(raw.channels.discord)) {
+    return [];
+  }
+
+  const candidates: UnsupportedSecretRefConfigCandidate[] = [];
+  const discord = raw.channels.discord;
+  const threadBindings = isRecord(discord.threadBindings) ? discord.threadBindings : null;
+  if (threadBindings) {
+    candidates.push({
+      path: "channels.discord.threadBindings.webhookToken",
+      value: threadBindings.webhookToken,
+    });
+  }
+
+  const accounts = isRecord(discord.accounts) ? discord.accounts : null;
+  if (!accounts) {
+    return candidates;
+  }
+  for (const [accountId, account] of Object.entries(accounts)) {
+    if (!isRecord(account) || !isRecord(account.threadBindings)) {
+      continue;
+    }
+    candidates.push({
+      path: `channels.discord.accounts.${accountId}.threadBindings.webhookToken`,
+      value: account.threadBindings.webhookToken,
+    });
+  }
+  return candidates;
+}

package/src/security-doctor.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from "vitest";
+import { isDiscordMutableAllowEntry } from "./security-doctor.js";
+
+describe("discord security doctor helpers", () => {
+  it("rejects stable ids and wildcard forms", () => {
+    expect(isDiscordMutableAllowEntry("*")).toBe(false);
+    expect(isDiscordMutableAllowEntry("123456789")).toBe(false);
+    expect(isDiscordMutableAllowEntry("<@123456789>")).toBe(false);
+    expect(isDiscordMutableAllowEntry("user:123456789")).toBe(false);
+    expect(isDiscordMutableAllowEntry("pk:123456789")).toBe(false);
+  });
+
+  it("flags freeform names but not prefixed stable-id namespaces", () => {
+    expect(isDiscordMutableAllowEntry("alice")).toBe(true);
+    expect(isDiscordMutableAllowEntry("discord:alice")).toBe(false);
+    expect(isDiscordMutableAllowEntry("user:alice")).toBe(false);
+    expect(isDiscordMutableAllowEntry("pk:alice")).toBe(false);
+  });
+
+  it("treats empty prefixed entries as mutable placeholders", () => {
+    expect(isDiscordMutableAllowEntry("discord:")).toBe(true);
+    expect(isDiscordMutableAllowEntry("user:")).toBe(true);
+    expect(isDiscordMutableAllowEntry("pk:")).toBe(true);
+  });
+});

package/src/security-doctor.ts

@@ -0,0 +1,20 @@
+export function isDiscordMutableAllowEntry(raw: string): boolean {
+  const text = raw.trim();
+  if (!text || text === "*") {
+    return false;
+  }
+
+  const maybeMentionId = text.replace(/^<@!?/, "").replace(/>$/, "");
+  if (/^\d+$/.test(maybeMentionId)) {
+    return false;
+  }
+
+  for (const prefix of ["discord:", "user:", "pk:"]) {
+    if (!text.startsWith(prefix)) {
+      continue;
+    }
+    return text.slice(prefix.length).trim().length === 0;
+  }
+
+  return true;
+}

package/src/security.ts

@@ -0,0 +1,60 @@
+import { createScopedDmSecurityResolver } from "openclaw/plugin-sdk/channel-config-helpers";
+import { createOpenProviderConfiguredRouteWarningCollector } from "openclaw/plugin-sdk/channel-policy";
+import {
+  resolveDiscordAccountAllowFrom,
+  resolveDiscordAccountDmPolicy,
+  type ResolvedDiscordAccount,
+} from "./accounts.js";
+import type { ChannelPlugin } from "./channel-api.js";
+
+const resolveDiscordDmPolicy = createScopedDmSecurityResolver<ResolvedDiscordAccount>({
+  channelKey: "discord",
+  resolvePolicy: (account) => account.config.dmPolicy,
+  resolveAllowFrom: (account) => account.config.allowFrom,
+  resolveAccess: ({ cfg, account }) => ({
+    dmPolicy: resolveDiscordAccountDmPolicy({ cfg, accountId: account.accountId }),
+    allowFrom: resolveDiscordAccountAllowFrom({ cfg, accountId: account.accountId }),
+  }),
+  policyPathSuffix: "dmPolicy",
+  normalizeEntry: (raw) =>
+    raw
+      .trim()
+      .replace(/^(discord|user):/i, "")
+      .replace(/^<@!?(\d+)>$/, "$1"),
+});
+
+const collectDiscordSecurityWarnings =
+  createOpenProviderConfiguredRouteWarningCollector<ResolvedDiscordAccount>({
+    providerConfigPresent: (cfg) => cfg.channels?.discord !== undefined,
+    resolveGroupPolicy: (account) => account.config.groupPolicy,
+    resolveRouteAllowlistConfigured: (account) =>
+      Object.keys(account.config.guilds ?? {}).length > 0,
+    configureRouteAllowlist: {
+      surface: "Discord guilds",
+      openScope: "any channel not explicitly denied",
+      groupPolicyPath: "channels.discord.groupPolicy",
+      routeAllowlistPath: "channels.discord.guilds.<id>.channels",
+    },
+    missingRouteAllowlist: {
+      surface: "Discord guilds",
+      openBehavior: "with no guild/channel allowlist; any channel can trigger (mention-gated)",
+      remediation:
+        'Set channels.discord.groupPolicy="allowlist" and configure channels.discord.guilds.<id>.channels',
+    },
+  });
+
+let discordSecurityAuditModulePromise:
+  | Promise<typeof import("./security-audit.runtime.js")>
+  | undefined;
+
+async function loadDiscordSecurityAuditModule() {
+  discordSecurityAuditModulePromise ??= import("./security-audit.runtime.js");
+  return await discordSecurityAuditModulePromise;
+}
+
+export const discordSecurityAdapter = {
+  resolveDmPolicy: resolveDiscordDmPolicy,
+  collectWarnings: collectDiscordSecurityWarnings,
+  collectAuditFindings: async (params) =>
+    (await loadDiscordSecurityAuditModule()).collectDiscordSecurityAuditFindings(params),
+} satisfies NonNullable<ChannelPlugin<ResolvedDiscordAccount>["security"]>;

package/src/send-target-parsing.ts

@@ -0,0 +1,14 @@
+import {
+  parseDiscordTarget,
+  type DiscordTarget,
+  type DiscordTargetParseOptions,
+} from "./target-parsing.js";
+
+export type SendDiscordTarget = DiscordTarget;
+
+type SendDiscordTargetParseOptions = DiscordTargetParseOptions;
+
+export const parseDiscordSendTarget = (
+  raw: string,
+  options: SendDiscordTargetParseOptions = {},
+): SendDiscordTarget | undefined => parseDiscordTarget(raw, options);