@moxxy/plugin-channel-slack 0.27.0

package/src/keys.ts

@@ -0,0 +1,96 @@
+/**
+ * Vault keys + env overrides + token 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.
+ */
+import { z } from '@moxxy/sdk';
+import { resolveSecret } from '@moxxy/channel-kit';
+
+/** Vault key for the Slack bot OAuth token (`xoxb-…`). */
+export const SLACK_BOT_TOKEN_KEY = 'slack_bot_token';
+/** Vault key for the Slack app signing secret (HMAC over the raw request body). */
+export const SLACK_SIGNING_SECRET_KEY = 'slack_signing_secret';
+/**
+ * Vault key for the authorized team/channel set (TOFU pairing). Stored as a
+ * JSON string of an authorization record so we can grow what we pin without a
+ * format change (today: `{ teamId, channelId? }`).
+ */
+export const SLACK_AUTHORIZED_KEY = 'slack_authorized';
+
+/** Env override for the bot token (beats the vault, matching every other channel). */
+export const SLACK_BOT_TOKEN_ENV = 'MOXXY_SLACK_BOT_TOKEN';
+/** Env override for the signing secret. */
+export const SLACK_SIGNING_SECRET_ENV = 'MOXXY_SLACK_SIGNING_SECRET';
+
+/** A Slack bot token always starts with `xoxb-`. */
+export const SLACK_BOT_TOKEN_RE = /^xoxb-[A-Za-z0-9-]{10,}$/;
+
+/** zod validator for a bot token (shape only — connectivity is tested via `auth.test`). */
+export const slackBotTokenSchema = z
+  .string()
+  .trim()
+  .regex(SLACK_BOT_TOKEN_RE, 'expected a Slack bot token like "xoxb-…"');
+
+/** zod validator for a signing secret (hex-ish; Slack uses a 32-byte hex secret). */
+export const slackSigningSecretSchema = z
+  .string()
+  .trim()
+  .min(16, 'signing secret looks too short')
+  .max(256, 'signing secret looks too long');
+
+/**
+ * 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: SLACK_BOT_TOKEN_ENV, vaultKey: SLACK_BOT_TOKEN_KEY });
+}
+
+/** Resolve the signing secret: env override first, then the vault. */
+export async function resolveSigningSecret(vault: {
+  get(name: string): Promise<string | null>;
+}): Promise<string | null> {
+  return resolveSecret(vault, {
+    envVar: SLACK_SIGNING_SECRET_ENV,
+    vaultKey: SLACK_SIGNING_SECRET_KEY,
+  });
+}
+
+/** What we persist under {@link SLACK_AUTHORIZED_KEY}. */
+export interface SlackAuthorization {
+  readonly teamId: string;
+  /** Optionally narrow authorization to a single channel. */
+  readonly channelId?: string;
+}
+
+/** Parse the stored authorization record. Returns null for missing/corrupt. */
+export function parseAuthorization(raw: string | null | undefined): SlackAuthorization | null {
+  if (!raw) return null;
+  try {
+    const parsed = JSON.parse(raw) as Partial<SlackAuthorization>;
+    if (typeof parsed?.teamId === 'string' && parsed.teamId) {
+      return parsed.channelId
+        ? { teamId: parsed.teamId, channelId: parsed.channelId }
+        : { teamId: parsed.teamId };
+    }
+  } catch {
+    /* corrupt — treat as unpaired */
+  }
+  return null;
+}
+
+/** Does an inbound event from `(teamId, channelId)` match the stored authorization? */
+export function authorizationMatches(
+  auth: SlackAuthorization | null,
+  teamId: string | undefined,
+  channelId: string | undefined,
+): boolean {
+  if (!auth || !teamId) return false;
+  if (auth.teamId !== teamId) return false;
+  if (auth.channelId && auth.channelId !== channelId) return false;
+  return true;
+}

package/src/pair-flow.ts

@@ -0,0 +1,119 @@
+import { confirm, isCancel, log, outro, spinner } from '@clack/prompts';
+import { exitAfterPairRequested, type ChannelSubcommandContext } from '@moxxy/sdk';
+import type { VaultStore } from '@moxxy/plugin-vault';
+import { SlackChannel, type PairCandidate } from './channel.js';
+
+const ANSI = process.stdout.isTTY && !process.env.NO_COLOR;
+const dim = (s: string): string => (ANSI ? `\x1b[2m${s}\x1b[22m` : s);
+
+/**
+ * Drive the TOFU pairing flow end-to-end.
+ *
+ *   1. Build a SlackChannel from the subcommand ctx + wire the session's
+ *      permission resolver.
+ *   2. Subscribe to pair candidates BEFORE starting so the first @mention can't
+ *      race past us.
+ *   3. Start in `pair` mode (opens the tunnel; prints the Request URL).
+ *   4. Wait (with spinner) for the first verified inbound event.
+ *   5. Ask the operator to confirm the team/channel; on yes, persist it.
+ *   6. Hand off the running bot until Ctrl+C.
+ *
+ * Uses the default `proxyTunnel` provider (the channel imports it directly), so
+ * the public Request URL is available once the channel starts.
+ */
+export async function runSlackPairFlow(ctx: ChannelSubcommandContext): Promise<number> {
+  const session = ctx.session;
+  const channel = new SlackChannel({
+    vault: ctx.deps.vault as VaultStore,
+    logger: ctx.deps.logger as never,
+  });
+  session.setPermissionResolver(channel.permissionResolver);
+
+  let candidateResolve: ((c: PairCandidate) => void) | null = null;
+  const firstCandidate = new Promise<PairCandidate>((resolve) => {
+    candidateResolve = resolve;
+  });
+  const unsubscribe = channel.onPairCandidate((c) => {
+    candidateResolve?.(c);
+    candidateResolve = null;
+  });
+
+  outro(dim('opening pairing window…'));
+
+  let handle;
+  try {
+    handle = await channel.start({ session, pair: true });
+  } catch (err) {
+    unsubscribe();
+    log.error(`Could not start the Slack channel: ${err instanceof Error ? err.message : String(err)}`);
+    return 1;
+  }
+
+  const stopBot = async (): Promise<void> => {
+    unsubscribe();
+    try {
+      await handle.stop('wizard');
+    } catch {
+      /* ignore */
+    }
+  };
+
+  if (channel.requestUrl) {
+    log.info(
+      `Slack Request URL (paste into Event Subscriptions):\n  ${channel.requestUrl}\n` +
+        'Then mention the bot (@your-bot) in a channel to pair.',
+    );
+  }
+
+  const spin = spinner();
+  spin.start('Waiting for the first @mention from Slack…');
+
+  let candidate: PairCandidate;
+  try {
+    candidate = await firstCandidate;
+  } catch (err) {
+    spin.stop('pairing aborted');
+    log.error(`Pairing aborted: ${err instanceof Error ? err.message : String(err)}`);
+    await stopBot();
+    return 1;
+  }
+  spin.stop(`Got an event from team ${candidate.teamId}, channel ${candidate.channelId}.`);
+
+  const ok = await confirm({
+    message: `Authorize team ${candidate.teamId} / channel ${candidate.channelId}?`,
+  });
+  if (isCancel(ok) || !ok) {
+    log.warn('Pairing not confirmed.');
+    await stopBot();
+    return 0;
+  }
+
+  await channel.confirmPairing(candidate);
+  log.success(`Paired ✓ — team ${candidate.teamId} is authorized.`);
+
+  if (exitAfterPairRequested(ctx)) {
+    // Orchestrated pairing (`moxxy onboard`): hand control back — the caller
+    // starts the bot under its own service afterwards.
+    await stopBot();
+    return 0;
+  }
+
+  log.info('Bot is running. Press Ctrl+C to stop.');
+
+  const shutdown = async (): Promise<void> => {
+    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 {
+    await handle.running;
+    return 0;
+  } finally {
+    process.removeListener('SIGINT', onSignal);
+    process.removeListener('SIGTERM', onSignal);
+  }
+}

package/src/permission.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { PendingToolCall, PermissionContext } from '@moxxy/sdk';
+import { buildSlackPermissionResolver } from './permission.js';
+
+const ctx: PermissionContext = { sessionId: 's1' };
+function call(name: string): PendingToolCall {
+  return { callId: `c_${name}`, name, input: {} };
+}
+
+describe('buildSlackPermissionResolver', () => {
+  it('auto-approves a listed tool', async () => {
+    const r = buildSlackPermissionResolver({
+      allowedTools: ['Read', 'Grep'],
+      allToolNames: ['Read', 'Grep', 'Bash', 'Write'],
+    });
+    const d = await r.check(call('Read'), ctx);
+    expect(d.mode).not.toBe('deny');
+  });
+
+  it('denies an unlisted tool', async () => {
+    const r = buildSlackPermissionResolver({
+      allowedTools: ['Read'],
+      allToolNames: ['Read', 'Bash'],
+    });
+    const d = await r.check(call('Bash'), ctx);
+    expect(d.mode).toBe('deny');
+  });
+
+  it('denies everything when the allow-list is empty (read-only)', async () => {
+    const r = buildSlackPermissionResolver({
+      allowedTools: [],
+      allToolNames: ['Read', 'Bash'],
+    });
+    expect((await r.check(call('Read'), ctx)).mode).toBe('deny');
+    expect((await r.check(call('Bash'), ctx)).mode).toBe('deny');
+  });
+
+  it('expands "*" to every registered tool name', async () => {
+    const r = buildSlackPermissionResolver({
+      allowedTools: ['*'],
+      allToolNames: ['Read', 'Bash', 'Write'],
+    });
+    expect((await r.check(call('Read'), ctx)).mode).not.toBe('deny');
+    expect((await r.check(call('Bash'), ctx)).mode).not.toBe('deny');
+    expect((await r.check(call('Write'), ctx)).mode).not.toBe('deny');
+    // A name not in the registry is still denied even under '*'.
+    expect((await r.check(call('NotRegistered'), ctx)).mode).toBe('deny');
+  });
+
+  it('logs each auto-approved call', async () => {
+    const info = vi.fn();
+    const r = buildSlackPermissionResolver({
+      allowedTools: ['Read'],
+      allToolNames: ['Read'],
+      logger: { info },
+    });
+    await r.check(call('Read'), ctx);
+    expect(info).toHaveBeenCalledTimes(1);
+    expect(info.mock.calls[0]?.[0]).toMatch(/auto-approved/);
+    // A denial is NOT logged as an approval.
+    info.mockClear();
+    await r.check(call('Bash'), ctx);
+    expect(info).not.toHaveBeenCalled();
+  });
+});

package/src/permission.ts

@@ -0,0 +1,42 @@
+import { createAuditedAllowListResolver } from '@moxxy/channel-kit';
+import type { PermissionResolver } from '@moxxy/sdk';
+
+export interface SlackPermissionLogger {
+  info?(msg: string, meta?: Record<string, unknown>): void;
+}
+
+/**
+ * Build the Slack channel's autonomous permission resolver.
+ *
+ * The bot runs hands-off (no human-in-the-loop, like the HTTP channel): the
+ * operator declares trust upfront via `channels.slack.allowedTools`, and any
+ * tool NOT in that list is denied. The trust check + `'*'` expansion +
+ * audit-on-auto-approve wiring is the shared
+ * {@link createAuditedAllowListResolver} from `@moxxy/channel-kit` (which in
+ * turn reuses the SDK's `createAllowListResolver`: exact-name match →
+ * `allow_session`, else `deny`); this wrapper binds it to the Slack channel
+ * logger so every auto-approved call leaves a trail of what the autonomous run
+ * executed. An empty list denies everything (effectively read-only, since no
+ * side-effecting tool can run without a clicker).
+ *
+ * (Autonomous allow-list safety is a known trade-off; see TECH_DEBT — v1 has no
+ * Slack-button approval flow.)
+ */
+export function buildSlackPermissionResolver(opts: {
+  allowedTools: ReadonlyArray<string>;
+  allToolNames: ReadonlyArray<string>;
+  logger?: SlackPermissionLogger;
+}): PermissionResolver {
+  return createAuditedAllowListResolver({
+    name: 'slack-allow-list',
+    allowedTools: opts.allowedTools,
+    allToolNames: opts.allToolNames,
+    onAutoApprove: (call, { wildcard }) => {
+      opts.logger?.info?.('slack: auto-approved tool call', {
+        tool: call.name,
+        callId: call.callId,
+        wildcard,
+      });
+    },
+  });
+}

package/src/server/dedupe.ts

@@ -0,0 +1,7 @@
+/**
+ * Slack event idempotency cache. The implementation lives in
+ * `@moxxy/channel-kit` (the at-least-once delivery pattern is shared with
+ * every inbound-webhook channel and `@moxxy/plugin-webhooks`); re-exported
+ * here because it is part of this plugin's public API.
+ */
+export { DeliveryDedupeCache } from '@moxxy/channel-kit';

package/src/server/ingest-server.test.ts

@@ -0,0 +1,280 @@
+import { createHmac } from 'node:crypto';
+import { afterEach, describe, expect, it } from 'vitest';
+import { IngestServer, SLACK_EVENTS_PATH, type DispatchContext } from './ingest-server.js';
+import type { IngestServerHooks } from './ingest-server.js';
+import type { SlackEventCallback } from './schema.js';
+
+const SECRET = 'test-signing-secret-0123456789abcdef';
+const BOT_USER = 'UBOT';
+
+function sign(body: string, ts = Math.floor(Date.now() / 1000)): Record<string, string> {
+  const sig = `v0=${createHmac('sha256', SECRET).update(`v0:${ts}:${body}`).digest('hex')}`;
+  return { 'x-slack-request-timestamp': String(ts), 'x-slack-signature': sig };
+}
+
+interface Harness {
+  server: IngestServer;
+  url: string;
+  dispatched: DispatchContext[];
+  verified: SlackEventCallback[];
+  authorized: { teamId?: string; channel?: string } | null;
+  pairConsumes: boolean;
+  stop(): Promise<void>;
+}
+
+async function makeServer(over: Partial<IngestServerHooks> = {}): Promise<Harness> {
+  const dispatched: DispatchContext[] = [];
+  const verified: SlackEventCallback[] = [];
+  const state: { authorized: { teamId?: string; channel?: string } | null; pairConsumes: boolean } =
+    { authorized: { teamId: 'T1', channel: 'C1' }, pairConsumes: false };
+
+  const hooks: IngestServerHooks = {
+    botUserId: BOT_USER,
+    isAuthorized: (teamId, channel) =>
+      state.authorized != null &&
+      state.authorized.teamId === teamId &&
+      (state.authorized.channel === undefined || state.authorized.channel === channel),
+    onVerifiedEvent: (ev) => {
+      verified.push(ev);
+      return state.pairConsumes;
+    },
+    dispatch: (ctx) => dispatched.push(ctx),
+    ...over,
+  };
+
+  const server = new IngestServer({ signingSecret: SECRET, hooks });
+  const bound = await server.start();
+  const url = `http://${bound.host}:${bound.port}${SLACK_EVENTS_PATH}`;
+  return {
+    server,
+    url,
+    dispatched,
+    verified,
+    get authorized() {
+      return state.authorized;
+    },
+    set authorized(v) {
+      state.authorized = v;
+    },
+    get pairConsumes() {
+      return state.pairConsumes;
+    },
+    set pairConsumes(v) {
+      state.pairConsumes = v;
+    },
+    stop: () => server.stop(),
+  } as Harness;
+}
+
+function appMention(over: Partial<Record<string, unknown>> = {}): string {
+  return JSON.stringify({
+    type: 'event_callback',
+    team_id: 'T1',
+    event_id: 'Ev1',
+    event: {
+      type: 'app_mention',
+      user: 'U1',
+      text: '<@UBOT> hi',
+      channel: 'C1',
+      ts: '1700000000.000100',
+      ...over,
+    },
+  });
+}
+
+async function post(
+  url: string,
+  body: string,
+  headers: Record<string, string>,
+): Promise<{ status: number; json: unknown }> {
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', ...headers },
+    body,
+  });
+  let json: unknown = null;
+  try {
+    json = await res.json();
+  } catch {
+    /* no body */
+  }
+  return { status: res.status, json };
+}
+
+describe('IngestServer', () => {
+  let h: Harness;
+  afterEach(async () => {
+    await h?.stop();
+  });
+
+  it('rejects an unsigned request with 401 (before the session)', async () => {
+    h = await makeServer();
+    const body = appMention();
+    const res = await post(h.url, body, {}); // no signature headers
+    expect(res.status).toBe(401);
+    expect(h.dispatched).toHaveLength(0);
+  });
+
+  it('rejects a tampered body with 401', async () => {
+    h = await makeServer();
+    const body = appMention();
+    const headers = sign(body);
+    const res = await post(h.url, appMention({ text: 'tampered' }), headers);
+    expect(res.status).toBe(401);
+    expect(h.dispatched).toHaveLength(0);
+  });
+
+  it('answers the url_verification challenge', async () => {
+    h = await makeServer();
+    const body = JSON.stringify({ type: 'url_verification', challenge: 'abc123' });
+    const res = await post(h.url, body, sign(body));
+    expect(res.status).toBe(200);
+    expect(res.json).toEqual({ challenge: 'abc123' });
+    expect(h.dispatched).toHaveLength(0);
+  });
+
+  it('rejects a signed-but-malformed envelope with 400', async () => {
+    h = await makeServer();
+    const body = JSON.stringify({ type: 'event_callback' /* no event */ });
+    const res = await post(h.url, body, sign(body));
+    expect(res.status).toBe(400);
+    expect(h.dispatched).toHaveLength(0);
+  });
+
+  it('acks 200 and dispatches an authorized app_mention', async () => {
+    h = await makeServer();
+    const body = appMention();
+    const res = await post(h.url, body, sign(body));
+    expect(res.status).toBe(200);
+    expect(h.dispatched).toHaveLength(1);
+    expect(h.dispatched[0]).toMatchObject({ channel: 'C1', text: '<@UBOT> hi', teamId: 'T1' });
+    // thread_ts falls back to ts when absent.
+    expect(h.dispatched[0]?.threadTs).toBe('1700000000.000100');
+  });
+
+  it('threads under thread_ts when present', async () => {
+    h = await makeServer();
+    const body = appMention({ thread_ts: '1699999999.000001' });
+    await post(h.url, body, sign(body));
+    expect(h.dispatched[0]?.threadTs).toBe('1699999999.000001');
+  });
+
+  it('drops a duplicate event_id (acks 200, does not re-dispatch)', async () => {
+    h = await makeServer();
+    const body = appMention();
+    const headers = sign(body);
+    const first = await post(h.url, body, headers);
+    const second = await post(h.url, body, sign(body));
+    expect(first.status).toBe(200);
+    expect(second.status).toBe(200);
+    expect(h.dispatched).toHaveLength(1);
+  });
+
+  it('drops a Slack retry (X-Slack-Retry-Num) without dispatching', async () => {
+    h = await makeServer();
+    const body = appMention({ ts: '1700000000.999' });
+    const headers = { ...sign(body), 'x-slack-retry-num': '1' };
+    const res = await post(h.url, body, headers);
+    expect(res.status).toBe(200);
+    expect(h.dispatched).toHaveLength(0);
+  });
+
+  it("drops the bot's own message (bot_id / matching user)", async () => {
+    h = await makeServer();
+    const byBotId = appMention({ bot_id: 'B1', event_id: 'EvB1' });
+    await post(h.url, byBotId, sign(byBotId));
+    const byUser = appMention({ user: BOT_USER, event_id: 'EvB2' });
+    await post(h.url, byUser, sign(byUser));
+    expect(h.dispatched).toHaveLength(0);
+  });
+
+  it('drops an event from an unauthorized team/channel', async () => {
+    h = await makeServer();
+    h.authorized = { teamId: 'T-OTHER', channel: 'C-OTHER' };
+    const body = appMention();
+    const res = await post(h.url, body, sign(body));
+    expect(res.status).toBe(200);
+    expect(h.dispatched).toHaveLength(0);
+  });
+
+  it('lets the pairing hook consume the first verified event (no dispatch)', async () => {
+    h = await makeServer();
+    h.authorized = null; // not yet paired
+    h.pairConsumes = true;
+    const body = appMention();
+    const res = await post(h.url, body, sign(body));
+    expect(res.status).toBe(200);
+    expect(h.verified).toHaveLength(1);
+    expect(h.dispatched).toHaveLength(0);
+  });
+
+  it('ignores message events with an edit/system subtype', async () => {
+    h = await makeServer();
+    const body = JSON.stringify({
+      type: 'event_callback',
+      team_id: 'T1',
+      event_id: 'EvSub',
+      event: {
+        type: 'message',
+        subtype: 'message_changed',
+        channel: 'C1',
+        text: 'edited',
+        ts: '1700000000.1',
+      },
+    });
+    const res = await post(h.url, body, sign(body));
+    expect(res.status).toBe(200);
+    expect(h.dispatched).toHaveLength(0);
+  });
+
+  it('rejects an oversized body without ever dispatching', async () => {
+    const dispatched: DispatchContext[] = [];
+    const server = new IngestServer({
+      signingSecret: SECRET,
+      maxBodyBytes: 64,
+      hooks: {
+        botUserId: BOT_USER,
+        isAuthorized: () => true,
+        dispatch: (c) => dispatched.push(c),
+      },
+    });
+    const bound = await server.start();
+    const url = `http://${bound.host}:${bound.port}${SLACK_EVENTS_PATH}`;
+    const big = 'x'.repeat(500);
+    const body = JSON.stringify({ type: 'event_callback', big });
+    // readRequestBody destroys the socket once the cap is exceeded, so the
+    // client either sees a 413 or a dropped connection — both are acceptable
+    // "rejected, never reached the session" outcomes. What MUST hold is that
+    // the oversized body never drives a turn.
+    let status = 0;
+    try {
+      const res = await fetch(url, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', ...sign(body) },
+        body,
+      });
+      status = res.status;
+    } catch {
+      status = -1; // connection dropped by the size-cap socket destroy
+    }
+    expect([413, -1]).toContain(status);
+    expect(dispatched).toHaveLength(0);
+    await server.stop();
+    // Reassign h so afterEach's stop() is a no-op on an already-stopped server.
+    h = { stop: async () => {} } as Harness;
+  });
+
+  it('a handler error never escalates (returns 404/4xx for junk)', async () => {
+    h = await makeServer();
+    // GET on the events path is a 404, not a thrown error.
+    const res = await fetch(h.url, { method: 'GET' });
+    expect(res.status).toBe(404);
+  });
+
+  it('serves a health probe', async () => {
+    h = await makeServer();
+    const base = h.url.replace(SLACK_EVENTS_PATH, '/slack/health');
+    const res = await fetch(base, { method: 'GET' });
+    expect(res.status).toBe(200);
+  });
+});