@kodelyth/discord 2026.5.39 → 2026.5.42

package/src/voice/access.ts

@@ -0,0 +1,126 @@
+import { resolveCommandAuthorizedFromAuthorizers } from "klaw/plugin-sdk/command-auth-native";
+import type { KlawConfig } from "klaw/plugin-sdk/config-contracts";
+import type { DiscordAccountConfig } from "klaw/plugin-sdk/config-contracts";
+import { resolveOpenProviderRuntimeGroupPolicy } from "klaw/plugin-sdk/runtime-group-policy";
+import type { Guild } from "../internal/discord.js";
+import {
+  isDiscordGroupAllowedByPolicy,
+  resolveDiscordChannelConfigWithFallback,
+  type DiscordChannelConfigResolved,
+  resolveDiscordGuildEntry,
+  resolveDiscordMemberAccessState,
+  resolveDiscordOwnerAccess,
+} from "../monitor/allow-list.js";
+
+export async function authorizeDiscordVoiceIngress(params: {
+  cfg: KlawConfig;
+  discordConfig: DiscordAccountConfig;
+  accountId?: string;
+  groupPolicy?: "open" | "disabled" | "allowlist";
+  useAccessGroups?: boolean;
+  guild?: Guild<true> | Guild | null;
+  guildName?: string;
+  guildId: string;
+  channelId: string;
+  channelName?: string;
+  channelSlug: string;
+  parentId?: string;
+  parentName?: string;
+  parentSlug?: string;
+  scope?: "channel" | "thread";
+  channelLabel?: string;
+  memberRoleIds: string[];
+  ownerAllowFrom?: string[];
+  sender: { id: string; name?: string; tag?: string };
+}): Promise<
+  { ok: true; channelConfig?: DiscordChannelConfigResolved | null } | { ok: false; message: string }
+> {
+  const groupPolicy =
+    params.groupPolicy ??
+    resolveOpenProviderRuntimeGroupPolicy({
+      providerConfigPresent: params.cfg.channels?.discord !== undefined,
+      groupPolicy: params.discordConfig.groupPolicy,
+      defaultGroupPolicy: params.cfg.channels?.defaults?.groupPolicy,
+    }).groupPolicy;
+  const guild =
+    params.guild ??
+    ({ id: params.guildId, ...(params.guildName ? { name: params.guildName } : {}) } as Guild);
+  const guildInfo = resolveDiscordGuildEntry({
+    guild,
+    guildId: params.guildId,
+    guildEntries: params.discordConfig.guilds,
+  });
+  const channelConfig = params.channelId
+    ? resolveDiscordChannelConfigWithFallback({
+        guildInfo,
+        channelId: params.channelId,
+        channelName: params.channelName,
+        channelSlug: params.channelSlug,
+        parentId: params.parentId,
+        parentName: params.parentName,
+        parentSlug: params.parentSlug,
+        scope: params.scope,
+      })
+    : null;
+
+  if (channelConfig?.enabled === false) {
+    return { ok: false, message: "This channel is disabled." };
+  }
+
+  const channelAllowlistConfigured =
+    Boolean(guildInfo?.channels) && Object.keys(guildInfo?.channels ?? {}).length > 0;
+  if (!params.channelId && groupPolicy === "allowlist" && channelAllowlistConfigured) {
+    return {
+      ok: false,
+      message: `${params.channelLabel ?? "This channel"} is not allowlisted for voice commands.`,
+    };
+  }
+
+  const channelAllowed = channelConfig ? channelConfig.allowed : !channelAllowlistConfigured;
+  if (
+    !isDiscordGroupAllowedByPolicy({
+      groupPolicy,
+      guildAllowlisted: Boolean(guildInfo),
+      channelAllowlistConfigured,
+      channelAllowed,
+    }) ||
+    channelConfig?.allowed === false
+  ) {
+    return {
+      ok: false,
+      message: `${params.channelLabel ?? "This channel"} is not allowlisted for voice commands.`,
+    };
+  }
+
+  const { hasAccessRestrictions, memberAllowed } = resolveDiscordMemberAccessState({
+    channelConfig,
+    guildInfo,
+    memberRoleIds: params.memberRoleIds,
+    sender: params.sender,
+    allowNameMatching: false,
+  });
+
+  const { ownerAllowList, ownerAllowed } = resolveDiscordOwnerAccess({
+    allowFrom:
+      params.ownerAllowFrom ?? params.discordConfig.allowFrom ?? params.discordConfig.dm?.allowFrom,
+    sender: params.sender,
+    allowNameMatching: false,
+  });
+
+  const useAccessGroups = params.useAccessGroups ?? params.cfg.commands?.useAccessGroups !== false;
+  const authorizers = useAccessGroups
+    ? [
+        { configured: ownerAllowList != null, allowed: ownerAllowed },
+        { configured: hasAccessRestrictions, allowed: memberAllowed },
+      ]
+    : [{ configured: hasAccessRestrictions, allowed: memberAllowed }];
+
+  const commandAuthorized = resolveCommandAuthorizedFromAuthorizers({
+    useAccessGroups,
+    authorizers,
+    modeWhenAccessGroupsOff: "configured",
+  });
+  return commandAuthorized
+    ? { ok: true, channelConfig }
+    : { ok: false, message: "You are not authorized to use this command." };
+}

package/src/voice/audio.test.ts

@@ -0,0 +1,47 @@
+import { Readable } from "node:stream";
+import { describe, expect, it } from "vitest";
+import { decodeOpusStream, resolveOpusDecoderPreference } from "./audio.js";
+
+describe("discord voice opus decoder selection", () => {
+  it("defaults to the pure-JS opusscript decoder", async () => {
+    const verbose: string[] = [];
+    const warnings: string[] = [];
+    const previousPreference = process.env.KLAW_DISCORD_OPUS_DECODER;
+    delete process.env.KLAW_DISCORD_OPUS_DECODER;
+
+    try {
+      const decoded = await decodeOpusStream(Readable.from([]), {
+        onVerbose: (message) => verbose.push(message),
+        onWarn: (message) => warnings.push(message),
+      });
+
+      expect(decoded.length).toBe(0);
+      expect(verbose).toContain("opus decoder: opusscript");
+      expect(warnings).toEqual([]);
+    } finally {
+      if (previousPreference === undefined) {
+        delete process.env.KLAW_DISCORD_OPUS_DECODER;
+      } else {
+        process.env.KLAW_DISCORD_OPUS_DECODER = previousPreference;
+      }
+    }
+  });
+
+  it("requires an explicit preference for native opus", () => {
+    const previousPreference = process.env.KLAW_DISCORD_OPUS_DECODER;
+    delete process.env.KLAW_DISCORD_OPUS_DECODER;
+
+    try {
+      expect(resolveOpusDecoderPreference()).toBe("opusscript");
+      expect(resolveOpusDecoderPreference("opusscript")).toBe("opusscript");
+      expect(resolveOpusDecoderPreference("native")).toBe("native");
+      expect(resolveOpusDecoderPreference("@discordjs/opus")).toBe("native");
+    } finally {
+      if (previousPreference === undefined) {
+        delete process.env.KLAW_DISCORD_OPUS_DECODER;
+      } else {
+        process.env.KLAW_DISCORD_OPUS_DECODER = previousPreference;
+      }
+    }
+  });
+});

package/src/voice/audio.ts

@@ -0,0 +1,249 @@
+import fs from "node:fs/promises";
+import { createRequire } from "node:module";
+import type { Readable } from "node:stream";
+import { resamplePcm } from "klaw/plugin-sdk/realtime-voice";
+import { logVerbose, shouldLogVerbose } from "klaw/plugin-sdk/runtime-env";
+import { formatErrorMessage } from "klaw/plugin-sdk/ssrf-runtime";
+import { tempWorkspace, resolvePreferredKlawTmpDir } from "klaw/plugin-sdk/temp-path";
+
+const require = createRequire(import.meta.url);
+
+const SAMPLE_RATE = 48_000;
+const CHANNELS = 2;
+const BIT_DEPTH = 16;
+
+type OpusDecoder = {
+  decode: (buffer: Buffer) => Buffer;
+};
+
+type OpusDecoderFactory = {
+  load: () => OpusDecoder;
+  name: string;
+};
+
+type OpusDecoderPreference = "native" | "opusscript";
+
+let warnedOpusMissing = false;
+let cachedOpusDecoderFactory: OpusDecoderFactory | null | "unresolved" = "unresolved";
+
+function buildWavBuffer(pcm: Buffer): Buffer {
+  const blockAlign = (CHANNELS * BIT_DEPTH) / 8;
+  const byteRate = SAMPLE_RATE * blockAlign;
+  const header = Buffer.alloc(44);
+  header.write("RIFF", 0);
+  header.writeUInt32LE(36 + pcm.length, 4);
+  header.write("WAVE", 8);
+  header.write("fmt ", 12);
+  header.writeUInt32LE(16, 16);
+  header.writeUInt16LE(1, 20);
+  header.writeUInt16LE(CHANNELS, 22);
+  header.writeUInt32LE(SAMPLE_RATE, 24);
+  header.writeUInt32LE(byteRate, 28);
+  header.writeUInt16LE(blockAlign, 32);
+  header.writeUInt16LE(BIT_DEPTH, 34);
+  header.write("data", 36);
+  header.writeUInt32LE(pcm.length, 40);
+  return Buffer.concat([header, pcm]);
+}
+
+function resolveOpusDecoderFactory(params: {
+  onWarn: (message: string) => void;
+}): OpusDecoderFactory | null {
+  const nativeFactory: OpusDecoderFactory = {
+    name: "@discordjs/opus",
+    load: () => {
+      const DiscordOpus = require("@discordjs/opus") as {
+        OpusEncoder: new (
+          sampleRate: number,
+          channels: number,
+        ) => {
+          decode: (buffer: Buffer) => Buffer;
+        };
+      };
+      return new DiscordOpus.OpusEncoder(SAMPLE_RATE, CHANNELS);
+    },
+  };
+  const opusscriptFactory: OpusDecoderFactory = {
+    name: "opusscript",
+    load: () => {
+      const OpusScript = require("opusscript") as {
+        new (sampleRate: number, channels: number, application: number): OpusDecoder;
+        Application: { AUDIO: number };
+      };
+      return new OpusScript(SAMPLE_RATE, CHANNELS, OpusScript.Application.AUDIO);
+    },
+  };
+  const factories: OpusDecoderFactory[] =
+    resolveOpusDecoderPreference() === "native"
+      ? [nativeFactory, opusscriptFactory]
+      : [opusscriptFactory, nativeFactory];
+
+  const failures: string[] = [];
+  for (const factory of factories) {
+    try {
+      factory.load();
+      return factory;
+    } catch (err) {
+      failures.push(`${factory.name}: ${formatErrorMessage(err)}`);
+    }
+  }
+
+  if (!warnedOpusMissing) {
+    warnedOpusMissing = true;
+    params.onWarn(
+      `discord voice: no usable opus decoder available (${failures.join("; ")}); cannot decode voice audio`,
+    );
+  }
+  return null;
+}
+
+export function resolveOpusDecoderPreference(
+  value = process.env.KLAW_DISCORD_OPUS_DECODER,
+): OpusDecoderPreference {
+  const normalized = value?.trim().toLowerCase();
+  if (normalized === "native" || normalized === "@discordjs/opus") {
+    return "native";
+  }
+  return "opusscript";
+}
+
+function getOrCreateOpusDecoderFactory(params: {
+  onWarn: (message: string) => void;
+}): OpusDecoderFactory | null {
+  if (cachedOpusDecoderFactory !== "unresolved") {
+    return cachedOpusDecoderFactory;
+  }
+  cachedOpusDecoderFactory = resolveOpusDecoderFactory(params);
+  return cachedOpusDecoderFactory;
+}
+
+function createOpusDecoder(params: {
+  onWarn: (message: string) => void;
+}): { decoder: OpusDecoder; name: string } | null {
+  const factory = getOrCreateOpusDecoderFactory(params);
+  if (!factory) {
+    return null;
+  }
+  return { decoder: factory.load(), name: factory.name };
+}
+
+export async function decodeOpusStream(
+  stream: Readable,
+  params: { onVerbose: (message: string) => void; onWarn: (message: string) => void },
+): Promise<Buffer> {
+  const selected = createOpusDecoder({ onWarn: params.onWarn });
+  if (!selected) {
+    return Buffer.alloc(0);
+  }
+  params.onVerbose(`opus decoder: ${selected.name}`);
+  const chunks: Buffer[] = [];
+  try {
+    for await (const chunk of stream) {
+      if (!chunk || !(chunk instanceof Buffer) || chunk.length === 0) {
+        continue;
+      }
+      const decoded = selected.decoder.decode(chunk);
+      if (decoded && decoded.length > 0) {
+        chunks.push(Buffer.from(decoded));
+      }
+    }
+  } catch (err) {
+    if (shouldLogVerbose()) {
+      logVerbose(`discord voice: opus decode failed: ${formatErrorMessage(err)}`);
+    }
+  }
+  return chunks.length > 0 ? Buffer.concat(chunks) : Buffer.alloc(0);
+}
+
+export async function decodeOpusStreamChunks(
+  stream: Readable,
+  params: {
+    onChunk: (pcm48kStereo: Buffer) => void;
+    onVerbose: (message: string) => void;
+    onWarn: (message: string) => void;
+  },
+): Promise<void> {
+  const selected = createOpusDecoder({ onWarn: params.onWarn });
+  if (!selected) {
+    return;
+  }
+  params.onVerbose(`opus decoder: ${selected.name}`);
+  try {
+    for await (const chunk of stream) {
+      if (!chunk || !(chunk instanceof Buffer) || chunk.length === 0) {
+        continue;
+      }
+      const decoded = selected.decoder.decode(chunk);
+      if (decoded && decoded.length > 0) {
+        params.onChunk(Buffer.from(decoded));
+      }
+    }
+  } catch (err) {
+    if (shouldLogVerbose()) {
+      logVerbose(`discord voice: opus decode failed: ${formatErrorMessage(err)}`);
+    }
+  }
+}
+
+export function convertDiscordPcm48kStereoToRealtimePcm24kMono(pcm: Buffer): Buffer {
+  const frameCount = Math.floor(pcm.length / 4);
+  if (frameCount === 0) {
+    return Buffer.alloc(0);
+  }
+  const mono48k = Buffer.alloc(frameCount * 2);
+  for (let frame = 0; frame < frameCount; frame += 1) {
+    const offset = frame * 4;
+    const left = pcm.readInt16LE(offset);
+    const right = pcm.readInt16LE(offset + 2);
+    mono48k.writeInt16LE(Math.round((left + right) / 2), frame * 2);
+  }
+  return resamplePcm(mono48k, SAMPLE_RATE, 24_000);
+}
+
+export function convertRealtimePcm24kMonoToDiscordPcm48kStereo(pcm: Buffer): Buffer {
+  const mono48k = resamplePcm(pcm, 24_000, SAMPLE_RATE);
+  const sampleCount = Math.floor(mono48k.length / 2);
+  if (sampleCount === 0) {
+    return Buffer.alloc(0);
+  }
+  const stereo = Buffer.alloc(sampleCount * 4);
+  for (let sampleIndex = 0; sampleIndex < sampleCount; sampleIndex += 1) {
+    const sample = mono48k.readInt16LE(sampleIndex * 2);
+    const offset = sampleIndex * 4;
+    stereo.writeInt16LE(sample, offset);
+    stereo.writeInt16LE(sample, offset + 2);
+  }
+  return stereo;
+}
+
+function estimateDurationSeconds(pcm: Buffer): number {
+  const bytesPerSample = (BIT_DEPTH / 8) * CHANNELS;
+  if (bytesPerSample <= 0) {
+    return 0;
+  }
+  return pcm.length / (bytesPerSample * SAMPLE_RATE);
+}
+
+export async function writeVoiceWavFile(
+  pcm: Buffer,
+): Promise<{ path: string; durationSeconds: number }> {
+  const workspace = await tempWorkspace({
+    rootDir: resolvePreferredKlawTmpDir(),
+    prefix: "discord-voice-",
+  });
+  const wav = buildWavBuffer(pcm);
+  const filePath = await workspace.write("segment.wav", wav);
+  scheduleTempCleanup(workspace.dir);
+  return { path: filePath, durationSeconds: estimateDurationSeconds(pcm) };
+}
+
+function scheduleTempCleanup(tempDir: string, delayMs: number = 30 * 60 * 1000): void {
+  const timer = setTimeout(() => {
+    fs.rm(tempDir, { recursive: true, force: true }).catch((err) => {
+      if (shouldLogVerbose()) {
+        logVerbose(`discord voice: temp cleanup failed for ${tempDir}: ${formatErrorMessage(err)}`);
+      }
+    });
+  }, delayMs);
+  timer.unref();
+}

package/src/voice/capture-state.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  beginVoiceCapture,
+  clearVoiceCaptureFinalizeTimer,
+  createVoiceCaptureState,
+  finishVoiceCapture,
+  scheduleVoiceCaptureFinalize,
+} from "./capture-state.js";
+
+describe("voice capture state", () => {
+  it("increments generations per speaker", () => {
+    const state = createVoiceCaptureState();
+    const first = beginVoiceCapture(state, "u1", { destroy: vi.fn() } as never);
+    finishVoiceCapture(state, "u1", first);
+    const second = beginVoiceCapture(state, "u1", { destroy: vi.fn() } as never);
+
+    expect(first).toBe(1);
+    expect(second).toBe(2);
+  });
+
+  it("clears active speaker state before destroying a finalized capture", async () => {
+    vi.useFakeTimers();
+    try {
+      const state = createVoiceCaptureState();
+      const destroy = vi.fn(() => {
+        expect(state.activeSpeakers.has("u1")).toBe(false);
+        expect(state.activeCaptureStreams.has("u1")).toBe(false);
+      });
+      beginVoiceCapture(state, "u1", { destroy } as never);
+
+      expect(scheduleVoiceCaptureFinalize({ state, userId: "u1", delayMs: 1_200 })).toBe(true);
+      await vi.advanceTimersByTimeAsync(1_200);
+
+      expect(destroy).toHaveBeenCalledTimes(1);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("lets a pending finalize be canceled for the same generation", () => {
+    const state = createVoiceCaptureState();
+    const generation = beginVoiceCapture(state, "u1", { destroy: vi.fn() } as never);
+
+    expect(scheduleVoiceCaptureFinalize({ state, userId: "u1", delayMs: 1_200 })).toBe(true);
+    expect(clearVoiceCaptureFinalizeTimer(state, "u1", generation)).toBe(true);
+    expect(state.captureFinalizeTimers.has("u1")).toBe(false);
+  });
+});

package/src/voice/capture-state.ts

@@ -0,0 +1,120 @@
+import type { Readable } from "node:stream";
+
+type VoiceCaptureEntry = {
+  generation: number;
+  stream: Readable;
+};
+
+type VoiceCaptureFinalizeTimer = {
+  generation: number;
+  timer: ReturnType<typeof setTimeout>;
+};
+
+export type VoiceCaptureState = {
+  activeSpeakers: Set<string>;
+  activeCaptureStreams: Map<string, VoiceCaptureEntry>;
+  captureFinalizeTimers: Map<string, VoiceCaptureFinalizeTimer>;
+  captureGenerations: Map<string, number>;
+};
+
+export function createVoiceCaptureState(): VoiceCaptureState {
+  return {
+    activeSpeakers: new Set(),
+    activeCaptureStreams: new Map(),
+    captureFinalizeTimers: new Map(),
+    captureGenerations: new Map(),
+  };
+}
+
+export function stopVoiceCaptureState(state: VoiceCaptureState): void {
+  for (const { timer } of state.captureFinalizeTimers.values()) {
+    clearTimeout(timer);
+  }
+  state.captureFinalizeTimers.clear();
+  for (const { stream } of state.activeCaptureStreams.values()) {
+    stream.destroy();
+  }
+  state.activeCaptureStreams.clear();
+  state.captureGenerations.clear();
+  state.activeSpeakers.clear();
+}
+
+export function getActiveVoiceCapture(
+  state: VoiceCaptureState,
+  userId: string,
+): VoiceCaptureEntry | undefined {
+  return state.activeCaptureStreams.get(userId);
+}
+
+export function isVoiceCaptureActive(state: VoiceCaptureState, userId: string): boolean {
+  return state.activeSpeakers.has(userId);
+}
+
+export function clearVoiceCaptureFinalizeTimer(
+  state: VoiceCaptureState,
+  userId: string,
+  generation?: number,
+): boolean {
+  const scheduled = state.captureFinalizeTimers.get(userId);
+  if (!scheduled || (generation !== undefined && scheduled.generation !== generation)) {
+    return false;
+  }
+  clearTimeout(scheduled.timer);
+  state.captureFinalizeTimers.delete(userId);
+  return true;
+}
+
+export function beginVoiceCapture(
+  state: VoiceCaptureState,
+  userId: string,
+  stream: Readable,
+): number {
+  const generation = (state.captureGenerations.get(userId) ?? 0) + 1;
+  state.captureGenerations.set(userId, generation);
+  state.activeSpeakers.add(userId);
+  state.activeCaptureStreams.set(userId, { generation, stream });
+  clearVoiceCaptureFinalizeTimer(state, userId, generation);
+  return generation;
+}
+
+export function finishVoiceCapture(
+  state: VoiceCaptureState,
+  userId: string,
+  generation: number,
+): boolean {
+  clearVoiceCaptureFinalizeTimer(state, userId, generation);
+  const activeCapture = state.activeCaptureStreams.get(userId);
+  if (activeCapture?.generation !== generation) {
+    return false;
+  }
+  state.activeCaptureStreams.delete(userId);
+  state.activeSpeakers.delete(userId);
+  return true;
+}
+
+export function scheduleVoiceCaptureFinalize(params: {
+  state: VoiceCaptureState;
+  userId: string;
+  delayMs: number;
+  onFinalize?: (capture: VoiceCaptureEntry) => void;
+}): boolean {
+  const { state, userId, delayMs, onFinalize } = params;
+  const capture = state.activeCaptureStreams.get(userId);
+  if (!capture) {
+    return false;
+  }
+  clearVoiceCaptureFinalizeTimer(state, userId, capture.generation);
+  const timer = setTimeout(() => {
+    const activeCapture = state.activeCaptureStreams.get(userId);
+    if (!activeCapture || activeCapture.generation !== capture.generation) {
+      return;
+    }
+    state.captureFinalizeTimers.delete(userId);
+    state.activeCaptureStreams.delete(userId);
+    state.activeSpeakers.delete(userId);
+    onFinalize?.(activeCapture);
+    activeCapture.stream.destroy();
+  }, delayMs);
+  state.captureFinalizeTimers.set(userId, { generation: capture.generation, timer });
+  return true;
+}