@kodelyth/discord 2026.5.39 → 2026.5.42

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 "klaw/plugin-sdk/channel-config-helpers";
+import { createOpenProviderConfiguredRouteWarningCollector } from "klaw/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);

package/src/send.channels.ts

@@ -0,0 +1,139 @@
+import type { APIChannel } from "discord-api-types/v10";
+import {
+  createGuildChannel,
+  deleteChannel,
+  deleteChannelPermission,
+  editChannel,
+  moveGuildChannels,
+  putChannelPermission,
+} from "./internal/discord.js";
+import { resolveDiscordRest } from "./send.shared.js";
+import type {
+  DiscordChannelCreate,
+  DiscordChannelEdit,
+  DiscordChannelMove,
+  DiscordChannelPermissionSet,
+  DiscordReactOpts,
+} from "./send.types.js";
+
+export async function createChannelDiscord(
+  payload: DiscordChannelCreate,
+  opts: DiscordReactOpts,
+): Promise<APIChannel> {
+  const rest = resolveDiscordRest(opts);
+  const body: Record<string, unknown> = {
+    name: payload.name,
+  };
+  if (payload.type !== undefined) {
+    body.type = payload.type;
+  }
+  if (payload.parentId) {
+    body.parent_id = payload.parentId;
+  }
+  if (payload.topic) {
+    body.topic = payload.topic;
+  }
+  if (payload.position !== undefined) {
+    body.position = payload.position;
+  }
+  if (payload.nsfw !== undefined) {
+    body.nsfw = payload.nsfw;
+  }
+  return await createGuildChannel(rest, payload.guildId, {
+    body,
+  });
+}
+
+export async function editChannelDiscord(
+  payload: DiscordChannelEdit,
+  opts: DiscordReactOpts,
+): Promise<APIChannel> {
+  const rest = resolveDiscordRest(opts);
+  const body: Record<string, unknown> = {};
+  if (payload.name !== undefined) {
+    body.name = payload.name;
+  }
+  if (payload.topic !== undefined) {
+    body.topic = payload.topic;
+  }
+  if (payload.position !== undefined) {
+    body.position = payload.position;
+  }
+  if (payload.parentId !== undefined) {
+    body.parent_id = payload.parentId;
+  }
+  if (payload.nsfw !== undefined) {
+    body.nsfw = payload.nsfw;
+  }
+  if (payload.rateLimitPerUser !== undefined) {
+    body.rate_limit_per_user = payload.rateLimitPerUser;
+  }
+  if (payload.archived !== undefined) {
+    body.archived = payload.archived;
+  }
+  if (payload.locked !== undefined) {
+    body.locked = payload.locked;
+  }
+  if (payload.autoArchiveDuration !== undefined) {
+    body.auto_archive_duration = payload.autoArchiveDuration;
+  }
+  if (payload.availableTags !== undefined) {
+    body.available_tags = payload.availableTags.map((t) => ({
+      ...(t.id !== undefined && { id: t.id }),
+      name: t.name,
+      ...(t.moderated !== undefined && { moderated: t.moderated }),
+      ...(t.emoji_id !== undefined && { emoji_id: t.emoji_id }),
+      ...(t.emoji_name !== undefined && { emoji_name: t.emoji_name }),
+    }));
+  }
+  return await editChannel(rest, payload.channelId, {
+    body,
+  });
+}
+
+export async function deleteChannelDiscord(channelId: string, opts: DiscordReactOpts) {
+  const rest = resolveDiscordRest(opts);
+  await deleteChannel(rest, channelId);
+  return { ok: true, channelId };
+}
+
+export async function moveChannelDiscord(payload: DiscordChannelMove, opts: DiscordReactOpts) {
+  const rest = resolveDiscordRest(opts);
+  const body: Array<Record<string, unknown>> = [
+    {
+      id: payload.channelId,
+      ...(payload.parentId !== undefined && { parent_id: payload.parentId }),
+      ...(payload.position !== undefined && { position: payload.position }),
+    },
+  ];
+  await moveGuildChannels(rest, payload.guildId, { body });
+  return { ok: true };
+}
+
+export async function setChannelPermissionDiscord(
+  payload: DiscordChannelPermissionSet,
+  opts: DiscordReactOpts,
+) {
+  const rest = resolveDiscordRest(opts);
+  const body: Record<string, unknown> = {
+    type: payload.targetType,
+  };
+  if (payload.allow !== undefined) {
+    body.allow = payload.allow;
+  }
+  if (payload.deny !== undefined) {
+    body.deny = payload.deny;
+  }
+  await putChannelPermission(rest, payload.channelId, payload.targetId, { body });
+  return { ok: true };
+}
+
+export async function removeChannelPermissionDiscord(
+  channelId: string,
+  targetId: string,
+  opts: DiscordReactOpts,
+) {
+  const rest = resolveDiscordRest(opts);
+  await deleteChannelPermission(rest, channelId, targetId);
+  return { ok: true };
+}

package/src/send.components.test.ts

@@ -0,0 +1,330 @@
+import { ChannelType, MessageFlags } from "discord-api-types/v10";
+import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { makeDiscordRest } from "./send.test-harness.js";
+
+const loadConfigMock = vi.hoisted(() => vi.fn(() => ({ session: { dmScope: "main" } })));
+
+const DISCORD_TEST_CFG = {
+  channels: {
+    discord: {
+      accounts: {
+        default: {},
+      },
+    },
+  },
+  session: { dmScope: "main" },
+} as const;
+
+vi.mock("klaw/plugin-sdk/plugin-config-runtime", async () => {
+  const actual = await vi.importActual<typeof import("klaw/plugin-sdk/plugin-config-runtime")>(
+    "klaw/plugin-sdk/plugin-config-runtime",
+  );
+  return {
+    ...actual,
+    loadConfig: (..._args: unknown[]) => loadConfigMock(),
+  };
+});
+
+vi.mock("./components-registry.js", () => ({
+  registerDiscordComponentEntries: vi.fn(),
+}));
+
+const sendMessageDiscordMock = vi.hoisted(() => vi.fn());
+vi.mock("./send.outbound.js", () => ({
+  sendMessageDiscord: sendMessageDiscordMock,
+}));
+
+const loadOutboundMediaFromUrlMock = vi.hoisted(() => vi.fn());
+vi.mock("./runtime-api.js", () => ({
+  loadOutboundMediaFromUrl: loadOutboundMediaFromUrlMock,
+}));
+
+let registerDiscordComponentEntries: typeof import("./components-registry.js").registerDiscordComponentEntries;
+let editDiscordComponentMessage: typeof import("./send.components.js").editDiscordComponentMessage;
+let registerBuiltDiscordComponentMessage: typeof import("./send.components.js").registerBuiltDiscordComponentMessage;
+let sendDiscordComponentMessage: typeof import("./send.components.js").sendDiscordComponentMessage;
+
+function resetClassicMocks(): void {
+  sendMessageDiscordMock.mockReset();
+  sendMessageDiscordMock.mockResolvedValue({ messageId: "msg1", channelId: "chan-1" });
+  loadOutboundMediaFromUrlMock.mockReset();
+  loadOutboundMediaFromUrlMock.mockResolvedValue({
+    buffer: Buffer.from("media"),
+    fileName: "report.pdf",
+  });
+  vi.clearAllMocks();
+}
+
+function readMockCall(mock: ReturnType<typeof vi.fn>, callIndex: number): unknown[] {
+  const call = mock.mock.calls[callIndex];
+  if (!call) {
+    throw new Error(`expected mock call #${callIndex + 1}`);
+  }
+  return call;
+}
+
+function readMockCallArg(mock: ReturnType<typeof vi.fn>, callIndex: number, argIndex: number) {
+  const call = readMockCall(mock, callIndex);
+  if (argIndex >= call.length) {
+    throw new Error(`expected mock call #${callIndex + 1} argument #${argIndex + 1}`);
+  }
+  return call[argIndex];
+}
+
+function readRecordArg(
+  mock: ReturnType<typeof vi.fn>,
+  callIndex: number,
+  argIndex: number,
+): Record<string, unknown> {
+  const arg = readMockCallArg(mock, callIndex, argIndex);
+  if (!arg || typeof arg !== "object") {
+    throw new Error(`expected mock call #${callIndex + 1} object argument #${argIndex + 1}`);
+  }
+  return arg as Record<string, unknown>;
+}
+
+describe("sendDiscordComponentMessage", () => {
+  let registerMock: ReturnType<typeof vi.mocked<typeof registerDiscordComponentEntries>>;
+
+  beforeAll(async () => {
+    ({ registerDiscordComponentEntries } = await import("./components-registry.js"));
+    ({
+      editDiscordComponentMessage,
+      registerBuiltDiscordComponentMessage,
+      sendDiscordComponentMessage,
+    } = await import("./send.components.js"));
+  });
+
+  beforeEach(() => {
+    registerMock = vi.mocked(registerDiscordComponentEntries);
+    resetClassicMocks();
+  });
+
+  it("keeps direct-channel DM session keys on component entries", async () => {
+    const { rest, postMock, getMock } = makeDiscordRest();
+    getMock.mockResolvedValueOnce({
+      type: ChannelType.DM,
+      recipients: [{ id: "user-1" }],
+    });
+    postMock.mockResolvedValueOnce({ id: "msg1", channel_id: "dm-1" });
+
+    await sendDiscordComponentMessage(
+      "channel:dm-1",
+      {
+        blocks: [{ type: "actions", buttons: [{ label: "Tap" }] }],
+      },
+      {
+        cfg: DISCORD_TEST_CFG,
+        rest,
+        token: "t",
+        sessionKey: "agent:main:discord:channel:dm-1",
+        agentId: "main",
+      },
+    );
+
+    expect(registerMock).toHaveBeenCalledTimes(1);
+    const args = readRecordArg(registerMock, 0, 0);
+    expect((args.entries as Array<{ sessionKey?: string }>)[0]?.sessionKey).toBe(
+      "agent:main:discord:channel:dm-1",
+    );
+  });
+
+  it("edits component messages and refreshes component registry entries", async () => {
+    const { rest, patchMock, getMock } = makeDiscordRest();
+    getMock.mockResolvedValueOnce({
+      type: ChannelType.GuildText,
+      id: "chan-1",
+    });
+    patchMock.mockResolvedValueOnce({ id: "msg1", channel_id: "chan-1" });
+
+    await editDiscordComponentMessage(
+      "channel:chan-1",
+      "msg1",
+      {
+        text: "Updated picker",
+        blocks: [{ type: "actions", buttons: [{ label: "Tap" }] }],
+      },
+      {
+        cfg: DISCORD_TEST_CFG,
+        rest,
+        token: "t",
+        sessionKey: "agent:main:discord:channel:chan-1",
+        agentId: "main",
+      },
+    );
+
+    expect(patchMock).toHaveBeenCalledTimes(1);
+    const [patchUrl, patchRequest] = readMockCall(patchMock, 0) as [
+      string,
+      { body?: { flags?: unknown; components?: unknown[] } },
+    ];
+    expect(patchUrl).toContain("/channels/chan-1/messages/msg1");
+    expect(patchRequest?.body?.flags).toBe(MessageFlags.IsComponentsV2);
+    expect(Array.isArray(patchRequest?.body?.components)).toBe(true);
+    expect(patchRequest?.body?.components).toHaveLength(1);
+    expect(registerMock).toHaveBeenCalledTimes(1);
+    const args = readRecordArg(registerMock, 0, 0);
+    expect(args.messageId).toBe("msg1");
+    expect((args.entries as Array<{ sessionKey?: string }>)[0]?.sessionKey).toBe(
+      "agent:main:discord:channel:chan-1",
+    );
+  });
+
+  it("registers a prebuilt component message against an edited message id", () => {
+    registerBuiltDiscordComponentMessage({
+      messageId: "msg1",
+      buildResult: {
+        components: [],
+        entries: [{ id: "entry-1", kind: "button", label: "Tap" }],
+        modals: [{ id: "modal-1", title: "Modal", fields: [] }],
+      },
+    });
+
+    expect(registerMock).toHaveBeenCalledWith({
+      entries: [{ id: "entry-1", kind: "button", label: "Tap" }],
+      modals: [{ id: "modal-1", title: "Modal", fields: [] }],
+      messageId: "msg1",
+    });
+  });
+});
+
+describe("sendDiscordComponentMessage classic message downgrade", () => {
+  beforeEach(() => {
+    resetClassicMocks();
+  });
+
+  it("forwards mediaReadFile and mediaAccess to sendMessageDiscord", async () => {
+    const readFileMock = vi.fn().mockResolvedValue(Buffer.from("pdf"));
+    const mediaAccess = { localRoots: ["/tmp"], readFile: readFileMock };
+
+    await sendDiscordComponentMessage(
+      "channel:chan-1",
+      { blocks: [{ type: "text", text: "report" }] },
+      {
+        cfg: DISCORD_TEST_CFG,
+        token: "t",
+        mediaUrl: "https://example.com/report.pdf",
+        mediaReadFile: readFileMock,
+        mediaAccess,
+      },
+    );
+
+    expect(sendMessageDiscordMock).toHaveBeenCalledTimes(1);
+    expect(readMockCall(sendMessageDiscordMock, 0)).toEqual([
+      "channel:chan-1",
+      "report",
+      {
+        cfg: DISCORD_TEST_CFG,
+        accountId: undefined,
+        token: "t",
+        rest: undefined,
+        mediaUrl: "https://example.com/report.pdf",
+        filename: undefined,
+        mediaLocalRoots: undefined,
+        mediaReadFile: readFileMock,
+        mediaAccess,
+        replyTo: undefined,
+        silent: undefined,
+        textLimit: undefined,
+        maxLinesPerMessage: undefined,
+        tableMode: undefined,
+        chunkMode: undefined,
+      },
+    ]);
+  });
+
+  it("keeps modal component messages on the component path", async () => {
+    const { rest, postMock, getMock } = makeDiscordRest();
+    const registerMock = vi.mocked(registerDiscordComponentEntries);
+    getMock.mockResolvedValueOnce({
+      type: ChannelType.GuildText,
+      id: "chan-1",
+    });
+    postMock.mockResolvedValueOnce({ id: "msg1", channel_id: "chan-1" });
+
+    await sendDiscordComponentMessage(
+      "channel:chan-1",
+      {
+        text: "report",
+        modal: {
+          title: "Feedback",
+          fields: [{ type: "text", label: "Notes" }],
+        },
+      },
+      {
+        cfg: DISCORD_TEST_CFG,
+        rest,
+        token: "t",
+        mediaUrl: "https://example.com/report.pdf",
+      },
+    );
+
+    expect(sendMessageDiscordMock).not.toHaveBeenCalled();
+    expect(postMock).toHaveBeenCalledTimes(1);
+    expect(registerMock).toHaveBeenCalledTimes(1);
+    const registration = readRecordArg(registerMock, 0, 0);
+    const modals = registration.modals as Array<{
+      title?: string;
+      fields?: Array<{ label?: string }>;
+    }>;
+    expect(registration.messageId).toBe("msg1");
+    expect(modals).toHaveLength(1);
+    expect(modals[0]?.title).toBe("Feedback");
+    expect(modals[0]?.fields).toHaveLength(1);
+    expect(modals[0]?.fields?.[0]?.label).toBe("Notes");
+  });
+
+  it("keeps spoiler file blocks on the component path", async () => {
+    const { rest, postMock, getMock } = makeDiscordRest();
+    getMock.mockResolvedValueOnce({
+      type: ChannelType.GuildText,
+      id: "chan-1",
+    });
+    postMock.mockResolvedValueOnce({ id: "msg1", channel_id: "chan-1" });
+
+    await sendDiscordComponentMessage(
+      "channel:chan-1",
+      {
+        text: "report",
+        blocks: [{ type: "file", file: "attachment://report.pdf", spoiler: true }],
+      },
+      {
+        cfg: DISCORD_TEST_CFG,
+        rest,
+        token: "t",
+        mediaUrl: "https://example.com/report.pdf",
+      },
+    );
+
+    expect(sendMessageDiscordMock).not.toHaveBeenCalled();
+    expect(postMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("keeps container-styled messages on the component path", async () => {
+    const { rest, postMock, getMock } = makeDiscordRest();
+    getMock.mockResolvedValueOnce({
+      type: ChannelType.GuildText,
+      id: "chan-1",
+    });
+    postMock.mockResolvedValueOnce({ id: "msg1", channel_id: "chan-1" });
+
+    await sendDiscordComponentMessage(
+      "channel:chan-1",
+      {
+        text: "report",
+        container: {
+          accentColor: 0x00ff00,
+        },
+      },
+      {
+        cfg: DISCORD_TEST_CFG,
+        rest,
+        token: "t",
+        mediaUrl: "https://example.com/report.pdf",
+      },
+    );
+
+    expect(sendMessageDiscordMock).not.toHaveBeenCalled();
+    expect(postMock).toHaveBeenCalledTimes(1);
+  });
+});