@kodelyth/discord 2026.5.39 → 2026.5.42

package/src/audit-core.ts

@@ -0,0 +1,178 @@
+import { ChannelType } from "discord-api-types/v10";
+import type {
+  DiscordGuildChannelConfig,
+  DiscordGuildEntry,
+  KlawConfig,
+} from "klaw/plugin-sdk/config-contracts";
+import { formatErrorMessage } from "klaw/plugin-sdk/error-runtime";
+import { isRecord, normalizeOptionalString } from "klaw/plugin-sdk/string-coerce-runtime";
+
+type DiscordChannelPermissionsAuditEntry = {
+  channelId: string;
+  ok: boolean;
+  missing?: string[];
+  error?: string | null;
+  matchKey?: string;
+  matchSource?: "id";
+};
+
+export type DiscordChannelPermissionsAudit = {
+  ok: boolean;
+  checkedChannels: number;
+  unresolvedChannels: number;
+  channels: DiscordChannelPermissionsAuditEntry[];
+  elapsedMs: number;
+};
+
+const REQUIRED_TEXT_CHANNEL_PERMISSIONS = ["ViewChannel", "SendMessages"] as const;
+const REQUIRED_VOICE_CHANNEL_PERMISSIONS = [
+  "ViewChannel",
+  "Connect",
+  "Speak",
+  "SendMessages",
+  "ReadMessageHistory",
+] as const;
+
+export function resolveRequiredDiscordChannelPermissions(channelType?: number): string[] {
+  if (channelType === ChannelType.GuildVoice || channelType === ChannelType.GuildStageVoice) {
+    return [...REQUIRED_VOICE_CHANNEL_PERMISSIONS];
+  }
+  return [...REQUIRED_TEXT_CHANNEL_PERMISSIONS];
+}
+
+function shouldAuditChannelConfig(config: DiscordGuildChannelConfig | undefined) {
+  if (!config) {
+    return true;
+  }
+  if (config.enabled === false) {
+    return false;
+  }
+  return true;
+}
+
+function listConfiguredGuildChannelKeys(
+  guilds: Record<string, DiscordGuildEntry> | undefined,
+): string[] {
+  if (!guilds) {
+    return [];
+  }
+  const ids = new Set<string>();
+  for (const entry of Object.values(guilds)) {
+    if (!entry || typeof entry !== "object") {
+      continue;
+    }
+    const channelsRaw = (entry as { channels?: unknown }).channels;
+    if (!isRecord(channelsRaw)) {
+      continue;
+    }
+    for (const [key, value] of Object.entries(channelsRaw)) {
+      const channelId = normalizeOptionalString(key) ?? "";
+      if (!channelId) {
+        continue;
+      }
+      if (channelId === "*") {
+        continue;
+      }
+      if (!shouldAuditChannelConfig(value as DiscordGuildChannelConfig | undefined)) {
+        continue;
+      }
+      ids.add(channelId);
+    }
+  }
+  return [...ids].toSorted((a, b) => a.localeCompare(b));
+}
+
+export function collectDiscordAuditChannelIdsForGuilds(
+  guilds: Record<string, DiscordGuildEntry> | undefined,
+) {
+  const keys = listConfiguredGuildChannelKeys(guilds);
+  const channelIds = keys.filter((key) => /^\d+$/.test(key));
+  const unresolvedChannels = keys.length - channelIds.length;
+  return { channelIds, unresolvedChannels };
+}
+
+export function collectDiscordAuditChannelIdsForAccount(config: {
+  guilds?: Record<string, DiscordGuildEntry>;
+  voice?: { autoJoin?: Array<{ guildId?: string; channelId?: string }> };
+}) {
+  const collected = collectDiscordAuditChannelIdsForGuilds(config.guilds);
+  const channelIds = new Set(collected.channelIds);
+  let unresolvedVoiceChannels = 0;
+  for (const entry of config.voice?.autoJoin ?? []) {
+    const channelId = normalizeOptionalString(entry?.channelId) ?? "";
+    if (/^\d+$/.test(channelId)) {
+      channelIds.add(channelId);
+    } else if (channelId) {
+      unresolvedVoiceChannels++;
+    }
+  }
+  return {
+    channelIds: [...channelIds].toSorted((a, b) => a.localeCompare(b)),
+    unresolvedChannels: collected.unresolvedChannels + unresolvedVoiceChannels,
+  };
+}
+
+export async function auditDiscordChannelPermissionsWithFetcher(params: {
+  cfg: KlawConfig;
+  token: string;
+  accountId?: string | null;
+  channelIds: string[];
+  timeoutMs: number;
+  fetchChannelPermissions: (
+    channelId: string,
+    params: { cfg: KlawConfig; token: string; accountId?: string },
+  ) => Promise<{
+    permissions: string[];
+    channelType?: number;
+  }>;
+}): Promise<DiscordChannelPermissionsAudit> {
+  const started = Date.now();
+  const token = normalizeOptionalString(params.token) ?? "";
+  if (!token || params.channelIds.length === 0) {
+    return {
+      ok: true,
+      checkedChannels: 0,
+      unresolvedChannels: 0,
+      channels: [],
+      elapsedMs: Date.now() - started,
+    };
+  }
+
+  const channels: DiscordChannelPermissionsAuditEntry[] = [];
+
+  for (const channelId of params.channelIds) {
+    try {
+      const perms = await params.fetchChannelPermissions(channelId, {
+        cfg: params.cfg,
+        token,
+        accountId: params.accountId ?? undefined,
+      });
+      const required = resolveRequiredDiscordChannelPermissions(perms.channelType);
+      const missing = required.filter((p) => !perms.permissions.includes(p));
+      channels.push({
+        channelId,
+        ok: missing.length === 0,
+        missing: missing.length ? missing : undefined,
+        error: null,
+        matchKey: channelId,
+        matchSource: "id",
+      });
+    } catch (err) {
+      channels.push({
+        channelId,
+        ok: false,
+        error: formatErrorMessage(err),
+        matchKey: channelId,
+        matchSource: "id",
+      });
+    }
+  }
+
+  return {
+    ok: channels.every((c) => c.ok),
+    checkedChannels: channels.length,
+    unresolvedChannels: 0,
+    channels,
+    elapsedMs: Date.now() - started,
+  };
+}

package/src/audit.test.ts

@@ -0,0 +1,204 @@
+import { ChannelType } from "discord-api-types/v10";
+import type { KlawConfig } from "klaw/plugin-sdk/config-contracts";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  auditDiscordChannelPermissionsWithFetcher,
+  collectDiscordAuditChannelIdsForAccount,
+  collectDiscordAuditChannelIdsForGuilds,
+} from "./audit-core.js";
+
+const fetchChannelPermissionsDiscordMock = vi.fn();
+
+function readDiscordGuilds(cfg: KlawConfig) {
+  const guilds = cfg.channels?.discord?.guilds;
+  if (!guilds) {
+    throw new Error("expected discord guilds config");
+  }
+  return guilds;
+}
+
+describe("discord audit", () => {
+  beforeEach(() => {
+    fetchChannelPermissionsDiscordMock.mockReset();
+  });
+
+  it("collects numeric channel ids even when config uses allow=false and counts unresolved keys", async () => {
+    const cfg = {
+      channels: {
+        discord: {
+          enabled: true,
+          token: "t",
+          groupPolicy: "allowlist",
+          guilds: {
+            "123": {
+              channels: {
+                "111": { allow: true },
+                general: { allow: true },
+                "222": { allow: false },
+              },
+            },
+          },
+        },
+      },
+    } as unknown as KlawConfig;
+
+    const collected = collectDiscordAuditChannelIdsForGuilds(readDiscordGuilds(cfg));
+    expect(collected.channelIds).toEqual(["111", "222"]);
+    expect(collected.unresolvedChannels).toBe(1);
+
+    fetchChannelPermissionsDiscordMock.mockResolvedValueOnce({
+      channelId: "111",
+      permissions: ["ViewChannel"],
+      raw: "0",
+      isDm: false,
+    });
+    fetchChannelPermissionsDiscordMock.mockResolvedValueOnce({
+      channelId: "222",
+      permissions: ["ViewChannel", "SendMessages"],
+      raw: "0",
+      isDm: false,
+    });
+
+    const audit = await auditDiscordChannelPermissionsWithFetcher({
+      cfg,
+      token: "t",
+      accountId: "default",
+      channelIds: collected.channelIds,
+      timeoutMs: 1000,
+      fetchChannelPermissions: fetchChannelPermissionsDiscordMock,
+    });
+    expect(audit.ok).toBe(false);
+    expect(audit.channels).toHaveLength(2);
+    expect(audit.channels[0]?.channelId).toBe("111");
+    expect(audit.channels[0]?.missing).toContain("SendMessages");
+  });
+
+  it("does not count '*' wildcard key as unresolved channel", () => {
+    const cfg = {
+      channels: {
+        discord: {
+          enabled: true,
+          token: "t",
+          groupPolicy: "allowlist",
+          guilds: {
+            "123": {
+              channels: {
+                "111": { allow: true },
+                "*": { allow: true },
+              },
+            },
+          },
+        },
+      },
+    } as unknown as KlawConfig;
+
+    const collected = collectDiscordAuditChannelIdsForGuilds(readDiscordGuilds(cfg));
+    expect(collected.channelIds).toEqual(["111"]);
+    expect(collected.unresolvedChannels).toBe(0);
+  });
+
+  it("handles guild with only '*' wildcard and no numeric channel ids", () => {
+    const cfg = {
+      channels: {
+        discord: {
+          enabled: true,
+          token: "t",
+          groupPolicy: "allowlist",
+          guilds: {
+            "123": {
+              channels: {
+                "*": { allow: true },
+              },
+            },
+          },
+        },
+      },
+    } as unknown as KlawConfig;
+
+    const collected = collectDiscordAuditChannelIdsForGuilds(readDiscordGuilds(cfg));
+    expect(collected.channelIds).toStrictEqual([]);
+    expect(collected.unresolvedChannels).toBe(0);
+  });
+
+  it("collects audit channel ids without resolving SecretRef-backed Discord tokens", () => {
+    const cfg = {
+      channels: {
+        discord: {
+          enabled: true,
+          token: {
+            source: "env",
+            provider: "default",
+            id: "DISCORD_BOT_TOKEN",
+          },
+          guilds: {
+            "123": {
+              channels: {
+                "111": { allow: true },
+                general: { allow: true },
+              },
+            },
+          },
+        },
+      },
+    } as unknown as KlawConfig;
+
+    const collected = collectDiscordAuditChannelIdsForGuilds(readDiscordGuilds(cfg));
+    expect(collected.channelIds).toEqual(["111"]);
+    expect(collected.unresolvedChannels).toBe(1);
+  });
+
+  it("includes configured voice auto-join channels in permission audits", () => {
+    const collected = collectDiscordAuditChannelIdsForAccount({
+      guilds: {
+        "123": {
+          channels: {
+            "111": { enabled: true },
+          },
+        },
+      },
+      voice: {
+        autoJoin: [
+          { guildId: "123", channelId: "222" },
+          { guildId: "123", channelId: "general" },
+        ],
+      },
+    });
+
+    expect(collected.channelIds).toEqual(["111", "222"]);
+    expect(collected.unresolvedChannels).toBe(1);
+  });
+
+  it.each([ChannelType.GuildVoice, ChannelType.GuildStageVoice])(
+    "requires voice permissions for voice channel audit targets of type %s",
+    async (channelType) => {
+      const cfg = {
+        channels: {
+          discord: {
+            enabled: true,
+            token: "t",
+          },
+        },
+      } as unknown as KlawConfig;
+
+      fetchChannelPermissionsDiscordMock.mockResolvedValueOnce({
+        channelId: "222",
+        permissions: ["ViewChannel", "SendMessages"],
+        channelType,
+        raw: "0",
+        isDm: false,
+      });
+
+      const audit = await auditDiscordChannelPermissionsWithFetcher({
+        cfg,
+        token: "t",
+        accountId: "default",
+        channelIds: ["222"],
+        timeoutMs: 1000,
+        fetchChannelPermissions: fetchChannelPermissionsDiscordMock,
+      });
+
+      expect(audit.ok).toBe(false);
+      expect(audit.channels[0]?.missing).toEqual(["Connect", "Speak", "ReadMessageHistory"]);
+    },
+  );
+});

package/src/audit.ts

@@ -0,0 +1,32 @@
+import type { KlawConfig } from "klaw/plugin-sdk/config-contracts";
+import { inspectDiscordAccount } from "./account-inspect.js";
+import {
+  auditDiscordChannelPermissionsWithFetcher,
+  collectDiscordAuditChannelIdsForAccount,
+  type DiscordChannelPermissionsAudit,
+} from "./audit-core.js";
+import { fetchChannelPermissionsDiscord } from "./send.js";
+
+export function collectDiscordAuditChannelIds(params: {
+  cfg: KlawConfig;
+  accountId?: string | null;
+}) {
+  const account = inspectDiscordAccount({
+    cfg: params.cfg,
+    accountId: params.accountId,
+  });
+  return collectDiscordAuditChannelIdsForAccount(account.config);
+}
+
+export async function auditDiscordChannelPermissions(params: {
+  cfg: KlawConfig;
+  token: string;
+  accountId?: string | null;
+  channelIds: string[];
+  timeoutMs: number;
+}): Promise<DiscordChannelPermissionsAudit> {
+  return await auditDiscordChannelPermissionsWithFetcher({
+    ...params,
+    fetchChannelPermissions: fetchChannelPermissionsDiscord,
+  });
+}

package/src/channel-actions.contract.test.ts

@@ -0,0 +1,45 @@
+import { installChannelActionsContractSuite } from "klaw/plugin-sdk/channel-test-helpers";
+import type { KlawConfig } from "klaw/plugin-sdk/config-contracts";
+import { describe } from "vitest";
+import { discordPlugin } from "../api.js";
+
+describe("discord actions contract", () => {
+  installChannelActionsContractSuite({
+    plugin: discordPlugin,
+    cases: [
+      {
+        name: "describes configured Discord actions and capabilities",
+        cfg: {
+          channels: {
+            discord: {
+              token: "Bot token-main",
+              actions: {
+                polls: true,
+                reactions: true,
+                permissions: false,
+                messages: false,
+                pins: false,
+                threads: false,
+                search: false,
+                stickers: false,
+                memberInfo: false,
+                roleInfo: false,
+                emojiUploads: false,
+                stickerUploads: false,
+                channelInfo: false,
+                channels: false,
+                voiceStatus: false,
+                events: false,
+                roles: false,
+                moderation: false,
+                presence: false,
+              },
+            },
+          },
+        } as KlawConfig,
+        expectedActions: ["send", "poll", "react", "reactions", "emoji-list"],
+        expectedCapabilities: ["presentation"],
+      },
+    ],
+  });
+});

package/src/channel-actions.runtime.ts

@@ -0,0 +1 @@
+export { handleDiscordMessageAction } from "./actions/handle-action.js";