@kodelyth/discord 2026.5.39 → 2026.5.42

package/src/monitor/channel-access.ts

@@ -0,0 +1,102 @@
+function readDiscordChannelPropertySafe(channel: unknown, key: string): unknown {
+  if (!channel || typeof channel !== "object") {
+    return undefined;
+  }
+  try {
+    if (!(key in channel)) {
+      return undefined;
+    }
+    return (channel as Record<string, unknown>)[key];
+  } catch {
+    return undefined;
+  }
+}
+
+function resolveDiscordChannelStringPropertySafe(
+  channel: unknown,
+  key: string,
+): string | undefined {
+  const value = readDiscordChannelPropertySafe(channel, key);
+  return typeof value === "string" ? value : undefined;
+}
+
+function resolveDiscordChannelNumberPropertySafe(
+  channel: unknown,
+  key: string,
+): number | undefined {
+  const value = readDiscordChannelPropertySafe(channel, key);
+  return typeof value === "number" ? value : undefined;
+}
+
+const DISCORD_CHANNEL_SNAKE_CASE_ALIASES: Record<string, string> = {
+  ownerId: "owner_id",
+  parentId: "parent_id",
+};
+
+function resolveDiscordChannelStringWithAliasSafe(
+  channel: unknown,
+  camelKey: string,
+): string | undefined {
+  const camelValue = resolveDiscordChannelStringPropertySafe(channel, camelKey);
+  if (camelValue !== undefined) {
+    return camelValue;
+  }
+
+  const snakeKey = DISCORD_CHANNEL_SNAKE_CASE_ALIASES[camelKey];
+  if (!snakeKey) {
+    return undefined;
+  }
+
+  const directSnakeValue = resolveDiscordChannelStringPropertySafe(channel, snakeKey);
+  if (directSnakeValue !== undefined) {
+    return directSnakeValue;
+  }
+
+  const rawData = readDiscordChannelPropertySafe(channel, "rawData");
+  return resolveDiscordChannelStringPropertySafe(rawData, snakeKey);
+}
+
+export type DiscordChannelInfoSafe = {
+  name?: string;
+  topic?: string;
+  type?: number;
+  parentId?: string;
+  ownerId?: string;
+  parentName?: string;
+};
+
+export function resolveDiscordChannelNameSafe(channel: unknown): string | undefined {
+  return resolveDiscordChannelStringPropertySafe(channel, "name");
+}
+
+export function resolveDiscordChannelIdSafe(channel: unknown): string | undefined {
+  return resolveDiscordChannelStringPropertySafe(channel, "id");
+}
+
+export function resolveDiscordChannelTopicSafe(channel: unknown): string | undefined {
+  return resolveDiscordChannelStringPropertySafe(channel, "topic");
+}
+
+export function resolveDiscordChannelParentIdSafe(channel: unknown): string | undefined {
+  return resolveDiscordChannelStringWithAliasSafe(channel, "parentId");
+}
+
+export function resolveDiscordChannelOwnerIdSafe(channel: unknown): string | undefined {
+  return resolveDiscordChannelStringWithAliasSafe(channel, "ownerId");
+}
+
+export function resolveDiscordChannelParentSafe(channel: unknown): unknown {
+  return readDiscordChannelPropertySafe(channel, "parent");
+}
+
+export function resolveDiscordChannelInfoSafe(channel: unknown): DiscordChannelInfoSafe {
+  const parent = resolveDiscordChannelParentSafe(channel);
+  return {
+    name: resolveDiscordChannelNameSafe(channel),
+    topic: resolveDiscordChannelTopicSafe(channel),
+    type: resolveDiscordChannelNumberPropertySafe(channel, "type"),
+    parentId: resolveDiscordChannelParentIdSafe(channel),
+    ownerId: resolveDiscordChannelOwnerIdSafe(channel),
+    parentName: resolveDiscordChannelNameSafe(parent),
+  };
+}

package/src/monitor/commands.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from "vitest";
+import { resolveDiscordSlashCommandConfig } from "./commands.js";
+
+describe("resolveDiscordSlashCommandConfig", () => {
+  it("defaults ephemeral to true when undefined", () => {
+    const result = resolveDiscordSlashCommandConfig(undefined);
+    expect(result.ephemeral).toBe(true);
+  });
+
+  it("defaults ephemeral to true when not explicitly false", () => {
+    const result = resolveDiscordSlashCommandConfig({});
+    expect(result.ephemeral).toBe(true);
+  });
+
+  it("sets ephemeral to false when explicitly false", () => {
+    const result = resolveDiscordSlashCommandConfig({ ephemeral: false });
+    expect(result.ephemeral).toBe(false);
+  });
+
+  it("keeps ephemeral true when explicitly true", () => {
+    const result = resolveDiscordSlashCommandConfig({ ephemeral: true });
+    expect(result.ephemeral).toBe(true);
+  });
+});

package/src/monitor/commands.ts

@@ -0,0 +1,9 @@
+import type { DiscordSlashCommandConfig } from "klaw/plugin-sdk/config-contracts";
+
+export function resolveDiscordSlashCommandConfig(
+  raw?: DiscordSlashCommandConfig,
+): Required<DiscordSlashCommandConfig> {
+  return {
+    ephemeral: raw?.ephemeral !== false,
+  };
+}

package/src/monitor/dm-command-auth.test.ts

@@ -0,0 +1,274 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  resolveDiscordDmCommandAccess,
+  resolveDiscordTextCommandAccess,
+} from "./dm-command-auth.js";
+
+const canViewDiscordGuildChannelMock = vi.hoisted(() => vi.fn());
+type DiscordDmIngressAccess = Awaited<ReturnType<typeof resolveDiscordDmCommandAccess>>;
+
+vi.mock("../send.permissions.js", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../send.permissions.js")>();
+  return {
+    ...actual,
+    canViewDiscordGuildChannel: canViewDiscordGuildChannelMock,
+  };
+});
+
+function dmCommandAuthorized(result: DiscordDmIngressAccess): boolean {
+  return result.senderAccess.allowed ? result.commandAccess.authorized : false;
+}
+
+describe("resolveDiscordTextCommandAccess", () => {
+  const sender = {
+    id: "123",
+    name: "alice",
+    tag: "alice#0001",
+  };
+
+  it("authorizes guild text commands from owner allowlists", async () => {
+    const result = await resolveDiscordTextCommandAccess({
+      accountId: "default",
+      sender,
+      ownerAllowFrom: ["discord:123"],
+      memberAccessConfigured: false,
+      memberAllowed: false,
+      allowNameMatching: false,
+      allowTextCommands: true,
+      hasControlCommand: true,
+    });
+    expect(result.authorized).toBe(true);
+    expect(result.shouldBlockControlCommand).toBe(false);
+  });
+
+  it("authorizes guild text commands from member access facts", async () => {
+    const result = await resolveDiscordTextCommandAccess({
+      accountId: "default",
+      sender,
+      ownerAllowFrom: [],
+      memberAccessConfigured: true,
+      memberAllowed: true,
+      allowNameMatching: false,
+      allowTextCommands: true,
+      hasControlCommand: true,
+    });
+    expect(result.authorized).toBe(true);
+    expect(result.shouldBlockControlCommand).toBe(false);
+  });
+
+  it("blocks unauthorized guild text control commands", async () => {
+    const result = await resolveDiscordTextCommandAccess({
+      accountId: "default",
+      sender,
+      ownerAllowFrom: ["discord:999"],
+      memberAccessConfigured: true,
+      memberAllowed: false,
+      allowNameMatching: false,
+      allowTextCommands: true,
+      hasControlCommand: true,
+    });
+    expect(result.authorized).toBe(false);
+    expect(result.shouldBlockControlCommand).toBe(true);
+  });
+
+  it("preserves configured mode when access groups are disabled", async () => {
+    const result = await resolveDiscordTextCommandAccess({
+      accountId: "default",
+      sender,
+      ownerAllowFrom: [],
+      memberAccessConfigured: false,
+      memberAllowed: false,
+      allowNameMatching: false,
+      cfg: { commands: { useAccessGroups: false } },
+      allowTextCommands: true,
+      hasControlCommand: true,
+    });
+    expect(result.authorized).toBe(true);
+    expect(result.shouldBlockControlCommand).toBe(false);
+  });
+});
+
+describe("resolveDiscordDmCommandAccess", () => {
+  const sender = {
+    id: "123",
+    name: "alice",
+    tag: "alice#0001",
+  };
+
+  beforeEach(() => {
+    canViewDiscordGuildChannelMock.mockReset();
+  });
+
+  async function resolveOpenDmAccess(configuredAllowFrom: string[]) {
+    return await resolveDiscordDmCommandAccess({
+      accountId: "default",
+      dmPolicy: "open",
+      configuredAllowFrom,
+      sender,
+      allowNameMatching: false,
+      readStoreAllowFrom: async () => [],
+    });
+  }
+
+  it("blocks open DMs without allowlist wildcard entries", async () => {
+    const result = await resolveOpenDmAccess([]);
+
+    expect(result.senderAccess.decision).toBe("block");
+    expect(dmCommandAuthorized(result)).toBe(false);
+  });
+
+  it("marks command auth true when sender is allowlisted", async () => {
+    const result = await resolveOpenDmAccess(["discord:123"]);
+
+    expect(result.senderAccess.decision).toBe("allow");
+    expect(dmCommandAuthorized(result)).toBe(true);
+  });
+
+  it("blocks open DMs when configured allowlist does not match", async () => {
+    const result = await resolveDiscordDmCommandAccess({
+      accountId: "default",
+      dmPolicy: "open",
+      configuredAllowFrom: ["discord:999"],
+      sender,
+      allowNameMatching: false,
+      readStoreAllowFrom: async () => [],
+    });
+
+    expect(result.senderAccess.decision).toBe("block");
+    expect(result.senderAccess.reasonCode).toBe("dm_policy_not_allowlisted");
+    expect(dmCommandAuthorized(result)).toBe(false);
+  });
+
+  it("returns pairing decision and unauthorized command auth for unknown senders", async () => {
+    const result = await resolveDiscordDmCommandAccess({
+      accountId: "default",
+      dmPolicy: "pairing",
+      configuredAllowFrom: ["discord:456"],
+      sender,
+      allowNameMatching: false,
+      readStoreAllowFrom: async () => [],
+    });
+
+    expect(result.senderAccess.decision).toBe("pairing");
+    expect(dmCommandAuthorized(result)).toBe(false);
+  });
+
+  it("authorizes sender from pairing-store allowlist entries", async () => {
+    const result = await resolveDiscordDmCommandAccess({
+      accountId: "default",
+      dmPolicy: "pairing",
+      configuredAllowFrom: [],
+      sender,
+      allowNameMatching: false,
+      readStoreAllowFrom: async () => ["discord:123"],
+    });
+
+    expect(result.senderAccess.decision).toBe("allow");
+    expect(dmCommandAuthorized(result)).toBe(true);
+  });
+
+  it("authorizes allowlist DMs from a Discord channel audience access group", async () => {
+    canViewDiscordGuildChannelMock.mockResolvedValueOnce(true);
+
+    const result = await resolveDiscordDmCommandAccess({
+      accountId: "default",
+      dmPolicy: "allowlist",
+      configuredAllowFrom: ["accessGroup:maintainers"],
+      sender,
+      allowNameMatching: false,
+      cfg: {
+        accessGroups: {
+          maintainers: {
+            type: "discord.channelAudience",
+            guildId: "guild-1",
+            channelId: "channel-1",
+          },
+        },
+      },
+      token: "token",
+      readStoreAllowFrom: async () => [],
+    });
+
+    expect(canViewDiscordGuildChannelMock).toHaveBeenCalledWith("guild-1", "channel-1", "123", {
+      accountId: "default",
+      cfg: {
+        accessGroups: {
+          maintainers: {
+            type: "discord.channelAudience",
+            guildId: "guild-1",
+            channelId: "channel-1",
+          },
+        },
+      },
+      token: "token",
+    });
+    expect(result.senderAccess.decision).toBe("allow");
+    expect(dmCommandAuthorized(result)).toBe(true);
+  });
+
+  it("authorizes allowlist DMs from a generic message sender access group", async () => {
+    const result = await resolveDiscordDmCommandAccess({
+      accountId: "default",
+      dmPolicy: "allowlist",
+      configuredAllowFrom: ["accessGroup:owners"],
+      sender,
+      allowNameMatching: false,
+      cfg: {
+        accessGroups: {
+          owners: {
+            type: "message.senders",
+            members: {
+              discord: ["discord:123"],
+              telegram: ["987"],
+            },
+          },
+        },
+      },
+      readStoreAllowFrom: async () => [],
+    });
+
+    expect(canViewDiscordGuildChannelMock).not.toHaveBeenCalled();
+    expect(result.senderAccess.decision).toBe("allow");
+    expect(dmCommandAuthorized(result)).toBe(true);
+  });
+
+  it("fails closed when a Discord channel audience access group lookup rejects", async () => {
+    canViewDiscordGuildChannelMock.mockRejectedValueOnce(new Error("missing intent"));
+
+    const result = await resolveDiscordDmCommandAccess({
+      accountId: "default",
+      dmPolicy: "allowlist",
+      configuredAllowFrom: ["accessGroup:maintainers"],
+      sender,
+      allowNameMatching: false,
+      cfg: {
+        accessGroups: {
+          maintainers: {
+            type: "discord.channelAudience",
+            guildId: "guild-1",
+            channelId: "channel-1",
+          },
+        },
+      },
+      readStoreAllowFrom: async () => [],
+    });
+
+    expect(result.senderAccess.decision).toBe("block");
+    expect(dmCommandAuthorized(result)).toBe(false);
+  });
+
+  it("keeps open DM blocked without wildcard even when access groups are disabled", async () => {
+    const result = await resolveDiscordDmCommandAccess({
+      accountId: "default",
+      dmPolicy: "open",
+      configuredAllowFrom: [],
+      sender,
+      allowNameMatching: false,
+      cfg: { commands: { useAccessGroups: false } },
+      readStoreAllowFrom: async () => [],
+    });
+
+    expect(result.senderAccess.decision).toBe("block");
+    expect(dmCommandAuthorized(result)).toBe(false);
+  });
+});

package/src/monitor/dm-command-auth.ts

@@ -0,0 +1,259 @@
+import {
+  type AccessGroupMembershipFact,
+  type ChannelIngressEventInput,
+  type ChannelIngressIdentifierKind,
+  createChannelIngressResolver,
+  defineStableChannelIngressIdentity,
+  type ChannelIngressIdentitySubjectInput,
+  type ResolveChannelMessageIngressParams,
+} from "klaw/plugin-sdk/channel-ingress-runtime";
+import type { KlawConfig } from "klaw/plugin-sdk/config-contracts";
+import { logVerbose } from "klaw/plugin-sdk/runtime-env";
+import type { RequestClient } from "../internal/discord.js";
+import { canViewDiscordGuildChannel } from "../send.permissions.js";
+import { normalizeDiscordAllowList } from "./allow-list.js";
+
+const DISCORD_ALLOW_LIST_PREFIXES = ["discord:", "user:", "pk:"];
+const DISCORD_CHANNEL_ID = "discord";
+const DISCORD_USER_ID_KIND = "stable-id" satisfies ChannelIngressIdentifierKind;
+const DISCORD_USER_NAME_KIND = "username" satisfies ChannelIngressIdentifierKind;
+
+export type DiscordDmPolicy = "open" | "pairing" | "allowlist" | "disabled";
+
+function normalizeDiscordIdEntry(entry: string): string | null {
+  const text = entry.trim();
+  if (!text) {
+    return null;
+  }
+  const maybeId = text.replace(/^<@!?/, "").replace(/>$/, "");
+  if (/^\d+$/.test(maybeId)) {
+    return maybeId;
+  }
+  const prefix = DISCORD_ALLOW_LIST_PREFIXES.find((entryPrefix) => text.startsWith(entryPrefix));
+  if (prefix) {
+    const candidate = text.slice(prefix.length).trim();
+    return candidate || null;
+  }
+  return null;
+}
+
+function normalizeDiscordNameEntry(entry: string): string | null {
+  const text = entry.trim();
+  if (!text || text === "*" || normalizeDiscordIdEntry(text)) {
+    return null;
+  }
+  const nameSlug = normalizeDiscordAllowList([text], DISCORD_ALLOW_LIST_PREFIXES)
+    ?.names.values()
+    .next().value;
+  return typeof nameSlug === "string" && nameSlug ? nameSlug : null;
+}
+
+function normalizeDiscordNameSubject(value: string): string | null {
+  const nameSlug = normalizeDiscordAllowList([value], DISCORD_ALLOW_LIST_PREFIXES)
+    ?.names.values()
+    .next().value;
+  return typeof nameSlug === "string" && nameSlug ? nameSlug : null;
+}
+
+const discordIngressIdentity = defineStableChannelIngressIdentity({
+  key: "discordUserId",
+  kind: DISCORD_USER_ID_KIND,
+  normalizeEntry: normalizeDiscordIdEntry,
+  normalizeSubject: (value) => value.trim() || null,
+  sensitivity: "pii",
+  aliases: (
+    [
+      ["discordUserName", normalizeDiscordNameEntry],
+      ["discordUserTag", () => null],
+    ] as const
+  ).map(([key, normalizeEntry]) => ({
+    key,
+    kind: DISCORD_USER_NAME_KIND,
+    normalizeEntry,
+    normalizeSubject: normalizeDiscordNameSubject,
+    dangerous: true,
+    sensitivity: "pii",
+  })),
+});
+
+function createDiscordDmIngressSubject(sender: {
+  id: string;
+  name?: string;
+  tag?: string;
+}): ChannelIngressIdentitySubjectInput {
+  return {
+    stableId: sender.id,
+    aliases: {
+      discordUserName: sender.name,
+      discordUserTag: sender.tag,
+    },
+  };
+}
+
+function createDiscordDynamicAccessGroupResolver(params: {
+  cfg?: KlawConfig;
+  token?: string;
+  rest?: RequestClient;
+}): ResolveChannelMessageIngressParams["resolveAccessGroupMembership"] {
+  if (!params.cfg) {
+    return undefined;
+  }
+  const cfg = params.cfg;
+  return async ({ name, group, accountId, subject }) => {
+    if (group.type !== "discord.channelAudience") {
+      return false;
+    }
+    const senderId = String(subject.stableId ?? "").trim();
+    if (!senderId) {
+      return false;
+    }
+    const membership = group.membership ?? "canViewChannel";
+    if (membership !== "canViewChannel") {
+      return false;
+    }
+    try {
+      return await canViewDiscordGuildChannel(group.guildId, group.channelId, senderId, {
+        cfg,
+        accountId,
+        token: params.token,
+        rest: params.rest,
+      });
+    } catch (err) {
+      logVerbose(`discord: accessGroup:${name} lookup failed for user ${senderId}: ${String(err)}`);
+      throw err;
+    }
+  };
+}
+
+function createDiscordIngressResolver(params: {
+  accountId: string;
+  cfg?: KlawConfig;
+  token?: string;
+  rest?: RequestClient;
+  readStoreAllowFrom?: ResolveChannelMessageIngressParams["readStoreAllowFrom"];
+  useDefaultPairingStore?: boolean;
+}) {
+  return createChannelIngressResolver({
+    channelId: DISCORD_CHANNEL_ID,
+    accountId: params.accountId,
+    identity: discordIngressIdentity,
+    cfg: params.cfg,
+    resolveAccessGroupMembership: createDiscordDynamicAccessGroupResolver({
+      cfg: params.cfg,
+      token: params.token,
+      rest: params.rest,
+    }),
+    ...(params.readStoreAllowFrom ? { readStoreAllowFrom: params.readStoreAllowFrom } : {}),
+    ...(params.useDefaultPairingStore !== undefined
+      ? { useDefaultPairingStore: params.useDefaultPairingStore }
+      : {}),
+  });
+}
+
+function syntheticAccessGroupMembership(
+  groupName: string,
+  allowed: boolean,
+): AccessGroupMembershipFact {
+  return allowed
+    ? {
+        kind: "matched",
+        groupName,
+        source: "dynamic",
+        matchedEntryIds: [groupName],
+      }
+    : {
+        kind: "not-matched",
+        groupName,
+        source: "dynamic",
+      };
+}
+
+export async function resolveDiscordDmCommandAccess(params: {
+  accountId: string;
+  dmPolicy: DiscordDmPolicy;
+  configuredAllowFrom: string[];
+  sender: { id: string; name?: string; tag?: string };
+  allowNameMatching: boolean;
+  cfg?: KlawConfig;
+  token?: string;
+  rest?: RequestClient;
+  readStoreAllowFrom?: ResolveChannelMessageIngressParams["readStoreAllowFrom"];
+  eventKind?: ChannelIngressEventInput["kind"];
+}) {
+  return await createDiscordIngressResolver({
+    accountId: params.accountId,
+    cfg: params.cfg,
+    token: params.token,
+    rest: params.rest,
+    readStoreAllowFrom: params.readStoreAllowFrom,
+    useDefaultPairingStore: params.readStoreAllowFrom == null,
+  }).message({
+    subject: createDiscordDmIngressSubject(params.sender),
+    conversation: {
+      kind: "direct",
+      id: params.sender.id,
+    },
+    event: {
+      kind: params.eventKind ?? "native-command",
+      authMode: "inbound",
+      mayPair: true,
+    },
+    dmPolicy: params.dmPolicy,
+    groupPolicy: "disabled",
+    policy: {
+      mutableIdentifierMatching: params.allowNameMatching ? "enabled" : "disabled",
+    },
+    allowFrom: params.configuredAllowFrom,
+    command: {
+      hasControlCommand: false,
+      modeWhenAccessGroupsOff: "configured",
+    },
+  });
+}
+
+export async function resolveDiscordTextCommandAccess(params: {
+  accountId: string;
+  sender: { id: string; name?: string; tag?: string };
+  ownerAllowFrom?: string[];
+  memberAccessConfigured: boolean;
+  memberAllowed: boolean;
+  allowNameMatching: boolean;
+  allowTextCommands: boolean;
+  hasControlCommand: boolean;
+  cfg?: KlawConfig;
+  token?: string;
+  rest?: RequestClient;
+}) {
+  const ownerAllowFrom = (params.ownerAllowFrom ?? []).filter((entry) => entry.trim() !== "*");
+  const memberAccessGroup = "discord-member-access";
+  const commandGroup = params.memberAccessConfigured ? [`accessGroup:${memberAccessGroup}`] : [];
+  const accessGroupMembership = params.memberAccessConfigured
+    ? [syntheticAccessGroupMembership(memberAccessGroup, params.memberAllowed)]
+    : [];
+  const result = await createDiscordIngressResolver({
+    accountId: params.accountId,
+    cfg: params.cfg,
+    token: params.token,
+    rest: params.rest,
+  }).command({
+    subject: createDiscordDmIngressSubject(params.sender),
+    conversation: {
+      kind: "group",
+      id: "discord-command",
+    },
+    accessGroupMembership,
+    dmPolicy: "allowlist",
+    groupPolicy: "allowlist",
+    policy: {
+      mutableIdentifierMatching: params.allowNameMatching ? "enabled" : "disabled",
+    },
+    allowFrom: ownerAllowFrom,
+    groupAllowFrom: commandGroup,
+    command: {
+      allowTextCommands: params.allowTextCommands,
+      hasControlCommand: params.hasControlCommand,
+      modeWhenAccessGroupsOff: "configured",
+    },
+  });
+  return result.commandAccess;
+}