@moxxy/plugin-channel-discord 0.27.0

package/src/index.ts

@@ -0,0 +1,247 @@
+import { defineChannel, definePlugin, type LifecycleHooks, type Plugin } from '@moxxy/sdk';
+import type { VaultStore } from '@moxxy/plugin-vault';
+import { DiscordChannel } from './channel.js';
+import {
+  DISCORD_ALLOWED_CHANNELS_KEY,
+  DISCORD_AUTHORIZED_USER_KEY,
+  DISCORD_TOKEN_ENV,
+  DISCORD_TOKEN_KEY,
+  parseAllowedChannels,
+  parseAuthorizedUser,
+  resolveBotToken,
+} from './keys.js';
+import { runDiscordWizard } from './setup-wizard.js';
+import { runPairFlow } from './pair-flow.js';
+
+export {
+  DiscordChannel,
+  type DiscordChannelOptions,
+  type DiscordStartOpts,
+  type PairingConfirmResult,
+} from './channel.js';
+export { DiscordPermissionResolver, type PendingPermission } from './permission.js';
+export { DiscordApprovalResolver, type PendingApproval } from './approval.js';
+export {
+  armPairing,
+  clearDiscordPairing,
+  confirmPendingCode,
+  createDiscordPairingState,
+  isUserAuthorized,
+  mintCodeForPeer,
+  pairingPhase,
+  type DiscordPairingDecision,
+  type DiscordPairingPhase,
+  type DiscordPairingState,
+} from './pairing.js';
+export { gateInbound, type GateVerdict } from './allow-list.js';
+export { DiscordTurnRenderer, splitForDiscord, DISCORD_MESSAGE_LIMIT } from './render.js';
+export {
+  extractInboundMessage,
+  inboundMessageSchema,
+  MAX_AUDIO_BYTES,
+  MAX_CONTENT_CHARS,
+  type InboundAttachment,
+  type InboundMessage,
+} from './schema.js';
+export {
+  DISCORD_TOKEN_KEY,
+  DISCORD_AUTHORIZED_USER_KEY,
+  DISCORD_ALLOWED_CHANNELS_KEY,
+  DISCORD_TOKEN_ENV,
+  DISCORD_TOKEN_RE,
+  parseAuthorizedUser,
+  parseAllowedChannels,
+  serializeAllowedChannels,
+  resolveBotToken,
+} from './keys.js';
+
+export interface BuildDiscordPluginOptions {
+  /** Host-injected encrypted secret store (available immediately). */
+  readonly vault: VaultStore;
+}
+
+/**
+ * Build the Discord channel plugin with a host-injected vault (mirroring the
+ * Telegram plugin's vault injection).
+ */
+export function buildDiscordPlugin(opts: BuildDiscordPluginOptions): Plugin {
+  return makeDiscordPlugin(() => opts.vault);
+}
+
+/**
+ * Discovery-loadable default export: resolves the vault from the inter-plugin
+ * service registry in `onInit` (the vault plugin publishes `'vault'`). Requires
+ * `@moxxy/plugin-vault` to load first (declared in `package.json`
+ * `moxxy.requirements`). The channel + subcommands read the vault via
+ * `getVault()`, so resolution is deferred to call time — after `onInit` wired it.
+ */
+export const discordPlugin: Plugin = (() => {
+  let resolved: VaultStore | null = null;
+  const getVault = (): VaultStore => {
+    if (!resolved) {
+      throw new Error(
+        '@moxxy/plugin-channel-discord: the "vault" service is unavailable — @moxxy/plugin-vault must load first',
+      );
+    }
+    return resolved;
+  };
+  const hooks: LifecycleHooks = {
+    onInit: (ctx) => {
+      resolved = ctx.services.require<VaultStore>('vault');
+    },
+  };
+  return makeDiscordPlugin(getVault, hooks);
+})();
+
+// Discovery entry: `createPluginLoader` requires a default Plugin export.
+export default discordPlugin;
+
+function makeDiscordPlugin(getVault: () => VaultStore, hooks?: LifecycleHooks): Plugin {
+  return definePlugin({
+    name: '@moxxy/plugin-channel-discord',
+    version: '0.0.0',
+    ...(hooks ? { hooks } : {}),
+    channels: [
+      defineChannel({
+        name: 'discord',
+        description:
+          'Discord bot channel via discord.js (gateway). DM code pairing; streamed replies via message edits; button-based permission prompts.',
+        // Like Slack/Telegram, run on a dedicated, isolated runner (separate
+        // socket + sticky session) so the bot keeps its own persistent history
+        // apart from the user's desktop/TUI work. The gateway is an outbound
+        // WebSocket — no tunnel needed.
+        dedicatedRunner: true,
+        sessionSource: 'discord',
+        // Self-described config so a control surface (TUI `/channels`, `moxxy
+        // channels start`) can configure + run Discord without a hardcoded table.
+        config: {
+          fields: [
+            {
+              name: 'botToken',
+              label: 'Bot token',
+              vaultKey: DISCORD_TOKEN_KEY,
+              required: true,
+              secret: true,
+              placeholder: 'MTIz…abc.def…',
+              help: 'discord.com/developers → your app → Bot → Reset Token. Enable the MESSAGE CONTENT privileged intent on the same page.',
+            },
+          ],
+          hasRequestUrl: false,
+          runHint:
+            'Invite the bot to a server via the link shown, then DM it — it replies with a one-time code; finish with `moxxy discord pair` in a terminal.',
+          connect: {
+            kind: 'url',
+            title: 'Invite the bot',
+            hint: 'Open the link to invite the bot to your server, then DM it to receive a pairing code and finish with `moxxy discord pair`.',
+            openable: true,
+            openLabel: 'Open Discord authorization',
+          },
+        },
+        create: (deps) =>
+          new DiscordChannel({
+            vault: getVault(),
+            token: (deps.options?.['token'] as string | undefined) ?? undefined,
+            logger: deps.logger as never,
+            ...(typeof deps.options?.['editFrameMs'] === 'number'
+              ? { editFrameMs: deps.options['editFrameMs'] as number }
+              : {}),
+          }),
+        isAvailable: async () => {
+          // Env-first: a fully env-configured bot is available even in a probe
+          // context (e.g. the `moxxy channels` listing) where onInit has not
+          // yet wired the vault service, so `getVault()` would throw.
+          if (process.env[DISCORD_TOKEN_ENV]?.trim()) return { ok: true };
+          try {
+            if ((await resolveBotToken(getVault())) != null) return { ok: true };
+            return {
+              ok: false,
+              reason:
+                "No bot token. Set MOXXY_DISCORD_TOKEN, or store one in the vault as '" +
+                DISCORD_TOKEN_KEY +
+                "' via `moxxy discord setup`.",
+            };
+          } catch {
+            return {
+              ok: false,
+              reason: 'Set MOXXY_DISCORD_TOKEN to skip the vault, or unlock the vault first.',
+            };
+          }
+        },
+        interactiveCommand: 'setup',
+        subcommands: {
+          setup: {
+            description:
+              'Interactive setup: store a bot token (with privileged-intent guidance), pair an account, then start the bot. Shown by default for `moxxy discord` on a TTY.',
+            run: async (ctx) => {
+              // The wizard drives token entry + pairing through clack prompts,
+              // so it needs an interactive terminal. In a headless invocation
+              // we just start the bot directly.
+              if (process.stdin.isTTY !== true) {
+                return ctx.startChannel();
+              }
+              return runDiscordWizard(ctx);
+            },
+          },
+          pair: {
+            description:
+              'DM code pairing: start the bot with a pairing window armed, DM it from your account, then paste the code it replies with.',
+            run: async (ctx) => {
+              // Pairing needs the operator to paste a code, so it needs an
+              // interactive terminal. In a headless invocation we bail with a
+              // clear message instead of starting a bot nobody can pair.
+              if (process.stdin.isTTY !== true) {
+                process.stderr.write(
+                  'Pairing needs a TTY (you paste the code the bot DMs back). Run `moxxy channels discord pair` on a workstation.\n',
+                );
+                return 1;
+              }
+              return runPairFlow(ctx);
+            },
+          },
+          unpair: {
+            description: 'Forget the currently authorized Discord account.',
+            run: async (ctx) => {
+              const vault = ctx.deps.vault as VaultStore | undefined;
+              if (!vault) {
+                process.stderr.write('vault unavailable\n');
+                return 1;
+              }
+              const removed = await vault.delete(DISCORD_AUTHORIZED_USER_KEY);
+              process.stdout.write(removed ? 'unpaired\n' : 'no pairing was active\n');
+              return 0;
+            },
+          },
+          status: {
+            description:
+              'Report whether a Discord token + an authorized account + allow-listed channels are configured.',
+            run: async (ctx) => {
+              const vault = ctx.deps.vault as VaultStore | undefined;
+              if (!vault) {
+                process.stderr.write('vault unavailable\n');
+                return 1;
+              }
+              const hasToken =
+                !!process.env[DISCORD_TOKEN_ENV]?.trim() || (await vault.has(DISCORD_TOKEN_KEY));
+              const authorized = await vault.get(DISCORD_AUTHORIZED_USER_KEY);
+              const allowed = parseAllowedChannels(
+                await vault.get(DISCORD_ALLOWED_CHANNELS_KEY),
+              );
+              process.stdout.write(
+                JSON.stringify(
+                  {
+                    tokenConfigured: hasToken,
+                    authorizedUserId: parseAuthorizedUser(authorized),
+                    allowedChannelIds: allowed,
+                  },
+                  null,
+                  2,
+                ) + '\n',
+              );
+              return 0;
+            },
+          },
+        },
+      }),
+    ],
+  });
+}

package/src/keys.ts

@@ -0,0 +1,100 @@
+/**
+ * Vault keys + env overrides + validators shared by the channel, its
+ * subcommands, and the interactive setup wizard. Kept in their own module so
+ * the wizard / pair-flow helpers can import them without pulling in the
+ * plugin's full index. The names here are the single source of truth for what
+ * the channel reads at boot (mirrored by the desktop channel catalog).
+ */
+import { z } from '@moxxy/sdk';
+import { resolveSecret } from '@moxxy/channel-kit';
+
+/** Vault key for the Discord bot token. */
+export const DISCORD_TOKEN_KEY = 'discord_bot_token';
+/** Vault key for the paired (authorized) Discord user id — the sole principal
+ *  allowed to drive the session. */
+export const DISCORD_AUTHORIZED_USER_KEY = 'discord_authorized_user_id';
+/** Vault key for the guild-channel allow-list (JSON array of channel ids the
+ *  paired user may drive the bot from, beyond their own DM). */
+export const DISCORD_ALLOWED_CHANNELS_KEY = 'discord_allowed_channel_ids';
+/**
+ * Vault key for the voice-replies preference. Single-paired-account model, so a
+ * present-flag (`'1'` = on, absent = off) toggled from a DM / allow-listed
+ * channel via `/voice`.
+ */
+export const DISCORD_VOICE_REPLIES_KEY = 'discord_voice_replies';
+
+/** Env override for the bot token (beats the vault, matching every other channel). */
+export const DISCORD_TOKEN_ENV = 'MOXXY_DISCORD_TOKEN';
+
+/**
+ * Shape-only validation of a Discord bot token: three dot-separated url-safe
+ * base64 segments (id.timestamp.hmac). Connectivity is proven by the gateway
+ * login, not here.
+ */
+export const DISCORD_TOKEN_RE = /^[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{20,}$/;
+
+/** A Discord snowflake id — numeric string, 5..25 digits. */
+export const snowflakeSchema = z.string().regex(/^\d{5,25}$/, 'expected a Discord snowflake id');
+
+/**
+ * Resolve the bot token: env override first, then the vault (the shared
+ * env→vault resolution in @moxxy/channel-kit). Returns null when neither is
+ * set. Trimmed; never returns an empty string.
+ */
+export async function resolveBotToken(vault: {
+  get(name: string): Promise<string | null>;
+}): Promise<string | null> {
+  return resolveSecret(vault, { envVar: DISCORD_TOKEN_ENV, vaultKey: DISCORD_TOKEN_KEY });
+}
+
+/**
+ * Parse the stored authorized-user id. Returns null for a missing OR corrupt
+ * value (anything that isn't a snowflake) so a bad vault write reads as
+ * "unpaired" instead of silently authorizing garbage.
+ */
+export function parseAuthorizedUser(raw: string | null | undefined): string | null {
+  if (!raw) return null;
+  const trimmed = raw.trim();
+  return snowflakeSchema.safeParse(trimmed).success ? trimmed : null;
+}
+
+const allowedChannelsSchema = z.array(snowflakeSchema);
+
+/**
+ * Parse the stored guild-channel allow-list (a JSON array of snowflakes).
+ * Corrupt/missing values read as the empty list — DENY every guild channel —
+ * rather than throwing or letting junk ids through.
+ */
+export function parseAllowedChannels(raw: string | null | undefined): ReadonlyArray<string> {
+  if (!raw) return [];
+  try {
+    const parsed = allowedChannelsSchema.safeParse(JSON.parse(raw));
+    return parsed.success ? parsed.data : [];
+  } catch {
+    return [];
+  }
+}
+
+/** Serialize the allow-list for the vault (deduplicated, stable order). */
+export function serializeAllowedChannels(ids: Iterable<string>): string {
+  return JSON.stringify([...new Set(ids)]);
+}
+
+/** Read the persisted voice-replies preference (`'1'` → on). */
+export async function loadVoiceReplies(vault: {
+  get(name: string): Promise<string | null>;
+}): Promise<boolean> {
+  return (await vault.get(DISCORD_VOICE_REPLIES_KEY)) === '1';
+}
+
+/** Persist the voice-replies preference: store `'1'` when on, remove it when off. */
+export async function saveVoiceReplies(
+  vault: {
+    set(name: string, value: string): Promise<void>;
+    delete(name: string): Promise<boolean>;
+  },
+  on: boolean,
+): Promise<void> {
+  if (on) await vault.set(DISCORD_VOICE_REPLIES_KEY, '1');
+  else await vault.delete(DISCORD_VOICE_REPLIES_KEY);
+}

package/src/pair-flow.ts

@@ -0,0 +1,122 @@
+import { isCancel, log, outro, spinner, text } from '@clack/prompts';
+import { exitAfterPairRequested, type ChannelSubcommandContext } from '@moxxy/sdk';
+import type { VaultStore } from '@moxxy/plugin-vault';
+import { DiscordChannel } from './channel.js';
+
+// Tiny zero-dep ANSI dim helper, so this flow stays inside the plugin.
+const ANSI = process.stdout.isTTY && !process.env.NO_COLOR;
+const dim = (s: string): string => (ANSI ? `\x1b[2m${s}\x1b[22m` : s);
+
+/** How many wrong codes the operator may paste before we give up. */
+const MAX_CODE_ATTEMPTS = 5;
+
+/**
+ * Drive the DM code pairing flow end-to-end in a terminal.
+ *
+ * Steps:
+ *   1. Build a DiscordChannel from the subcommand ctx and wire the session's
+ *      permission resolver.
+ *   2. Start the bot with the pairing window armed (`pair: true`).
+ *   3. Tell the user to DM the bot (from the account that should own it) —
+ *      the bot replies to that DM with a one-time code.
+ *   4. Prompt for the code here; on match that account is authorized and
+ *      persisted.
+ *   5. Keep the bot running until Ctrl+C (mirrors the Telegram pair flow).
+ */
+export async function runPairFlow(ctx: ChannelSubcommandContext): Promise<number> {
+  const session = ctx.session;
+  const channel = new DiscordChannel({
+    vault: ctx.deps.vault as VaultStore,
+    token: (ctx.deps.options?.['token'] as string | undefined) ?? undefined,
+    logger: ctx.deps.logger as never,
+  });
+  session.setPermissionResolver(channel.permissionResolver);
+
+  outro(dim('starting the bot with a pairing window armed...'));
+
+  const handle = await channel.start({ session, pair: true });
+
+  const stopBot = async (): Promise<void> => {
+    try {
+      await handle.stop('wizard');
+    } catch {
+      /* ignore */
+    }
+  };
+
+  // Already paired (no window armed): nothing to confirm. Tell the user how
+  // to re-pair rather than prompting for a code that can never arrive.
+  if (channel.connected) {
+    log.info(
+      'This bot is already paired. Run `moxxy channels discord unpair` first to pair a different account.',
+    );
+    await stopBot();
+    return 0;
+  }
+
+  if (channel.requestUrl) {
+    log.info(`Invite the bot to a server (needed once so you can DM it):\n  ${channel.requestUrl}`);
+  }
+  log.info(
+    'Now DM the bot from YOUR Discord account (any message). It replies with a one-time code — paste that code below.',
+  );
+
+  // Graceful Ctrl-C while waiting (or once running): stop the bot and exit.
+  let stopping = false;
+  const shutdown = async (): Promise<void> => {
+    if (stopping) return;
+    stopping = true;
+    await stopBot();
+    await session.close('SIGINT').catch(() => undefined);
+    process.exit(0);
+  };
+  const onSignal = (): void => void shutdown();
+  process.once('SIGINT', onSignal);
+  process.once('SIGTERM', onSignal);
+
+  try {
+    let paired = false;
+    for (let attempt = 0; attempt < MAX_CODE_ATTEMPTS && !paired; attempt++) {
+      const code = await text({
+        message: 'Paste the pairing code from the bot\'s DM reply',
+        placeholder: '6-digit code',
+        validate: (v) => (!v || !v.trim() ? 'required' : undefined),
+      });
+      if (isCancel(code)) {
+        log.info('Pairing cancelled.');
+        await stopBot();
+        return 0;
+      }
+      const result = await channel.confirmPairingCode(String(code));
+      if (result.ok) {
+        paired = true;
+        log.success(`Paired ✓ — Discord user ${result.userId} is authorized.`);
+        break;
+      }
+      log.warn(result.message);
+    }
+    if (!paired) {
+      log.error('Too many failed attempts — pairing aborted. Run `moxxy discord pair` to retry.');
+      await stopBot();
+      return 1;
+    }
+
+    if (exitAfterPairRequested(ctx)) {
+      // Orchestrated pairing (`moxxy onboard`): hand control back — the
+      // caller starts the bot under its own service afterwards.
+      await stopBot();
+      return 0;
+    }
+
+    const spin = spinner();
+    spin.start('Bot is running. Press Ctrl+C to stop.');
+    // Only reached if the bot stops on its own (a signal path exits via
+    // shutdown()).
+    await handle.running;
+    spin.stop('bot stopped.');
+    return 0;
+  } finally {
+    process.removeListener('SIGINT', onSignal);
+    process.removeListener('SIGTERM', onSignal);
+  }
+}

package/src/pairing.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, it } from 'vitest';
+import {
+  armPairing,
+  clearDiscordPairing,
+  confirmPendingCode,
+  createDiscordPairingState,
+  isUserAuthorized,
+  mintCodeForPeer,
+  pairingPhase,
+} from './pairing.js';
+
+const USER_A = '111111111111';
+const USER_B = '222222222222';
+
+describe('discord pairing state machine (DM code flow)', () => {
+  it('starts idle and unarmed; DMs get a "no window" rejection', () => {
+    const state = createDiscordPairingState();
+    expect(pairingPhase(state)).toBe('idle');
+    const decision = mintCodeForPeer(state, USER_A);
+    expect(decision.action.kind).toBe('reject');
+    expect(isUserAuthorized(decision.state, USER_A)).toBe(false);
+  });
+
+  it('mints a code for a DM-ing user once armed, then pairs on the pasted code', async () => {
+    let state = armPairing(createDiscordPairingState());
+    expect(pairingPhase(state)).toBe('armed');
+
+    const minted = mintCodeForPeer(state, USER_A, '123456');
+    expect(minted.action).toEqual({ kind: 'code-minted', userId: USER_A, code: '123456' });
+    state = minted.state;
+    expect(pairingPhase(state)).toBe('awaiting-host-code');
+
+    const confirmed = confirmPendingCode(state, ' 123 456 '); // whitespace tolerated
+    expect(confirmed.action).toEqual({ kind: 'paired', userId: USER_A });
+    expect(isUserAuthorized(confirmed.state, USER_A)).toBe(true);
+    expect(isUserAuthorized(confirmed.state, USER_B)).toBe(false);
+    expect(pairingPhase(confirmed.state)).toBe('paired');
+  });
+
+  it('rejects a wrong pasted code without transitioning', () => {
+    let state = armPairing(createDiscordPairingState());
+    state = mintCodeForPeer(state, USER_A, '123456').state;
+    const confirmed = confirmPendingCode(state, '654321');
+    expect(confirmed.action.kind).toBe('mismatch');
+    expect(isUserAuthorized(confirmed.state, USER_A)).toBe(false);
+    // The window stays open — the right code still pairs.
+    const retry = confirmPendingCode(confirmed.state, '123456');
+    expect(retry.action.kind).toBe('paired');
+  });
+
+  it('a second DM-ing user re-mints the window: the FIRST code goes stale (fails safe)', () => {
+    let state = armPairing(createDiscordPairingState());
+    const first = mintCodeForPeer(state, USER_A, '111111');
+    state = first.state;
+    const second = mintCodeForPeer(state, USER_B, '222222');
+    expect(second.action).toEqual({ kind: 'code-minted', userId: USER_B, code: '222222' });
+    state = second.state;
+    // Pasting USER_A's (stale) code must NOT pair anyone.
+    const stale = confirmPendingCode(state, '111111');
+    expect(stale.action.kind).toBe('mismatch');
+    expect(isUserAuthorized(stale.state, USER_A)).toBe(false);
+    expect(isUserAuthorized(stale.state, USER_B)).toBe(false);
+    // Pasting the CURRENT code pairs the user it was minted for.
+    const paired = confirmPendingCode(state, '222222');
+    expect(paired.action).toEqual({ kind: 'paired', userId: USER_B });
+  });
+
+  it('confirm without any pending DM is not-pending', () => {
+    const state = armPairing(createDiscordPairingState());
+    const confirmed = confirmPendingCode(state, '123456');
+    expect(confirmed.action.kind).toBe('not-pending');
+  });
+
+  it('a foreign user DM-ing a PAIRED bot is rejected; the paired user is greeted', () => {
+    const state = createDiscordPairingState({ authorizedUserId: USER_A });
+    expect(pairingPhase(state)).toBe('paired');
+    expect(mintCodeForPeer(state, USER_B).action.kind).toBe('reject');
+    expect(mintCodeForPeer(state, USER_A).action.kind).toBe('still-paired');
+  });
+
+  it('an expired code reports expired and clears the pending window', () => {
+    let state = armPairing(createDiscordPairingState());
+    // Arm with an explicit ttl through the kit path by minting then aging the
+    // confirm clock beyond a synthetic expiry: mint has no ttl by default, so
+    // simulate via a stale `now` only when expiresAt is set — the default is
+    // no-TTL, so this confirms the no-TTL behavior instead.
+    state = mintCodeForPeer(state, USER_A, '123456').state;
+    const decision = confirmPendingCode(state, '123456', Date.now() + 10 * 60_000);
+    // No TTL by default → still pairs even much later.
+    expect(decision.action.kind).toBe('paired');
+  });
+
+  it('clearDiscordPairing forgets the principal but keeps the armed flag', () => {
+    let state = armPairing(createDiscordPairingState({ authorizedUserId: USER_A }));
+    state = clearDiscordPairing(state);
+    expect(isUserAuthorized(state, USER_A)).toBe(false);
+    expect(pairingPhase(state)).toBe('armed');
+  });
+});