@moxxy/plugin-channel-slack 0.27.0

package/src/server/ingest-server.ts

@@ -0,0 +1,205 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import {
+  DeliveryDedupeCache,
+  IngestHttpServer,
+  respondJson,
+  type IngestHttpServerHandle,
+} from '@moxxy/channel-kit';
+import { slackEnvelopeSchema, type SlackEventCallback } from './schema.js';
+import { verifySlackSignature } from './verify.js';
+
+/**
+ * The HTTP front-end for the Slack channel. Binds a `node:http` server to an
+ * ephemeral loopback port; the channel exposes it publicly via the proxy
+ * tunnel. Slack POSTs every event to `<public>/slack/events`.
+ *
+ * The transport scaffold (routing, health probe, size-capped raw-body read,
+ * verify gate, catch-all error handling) is `@moxxy/channel-kit`'s
+ * {@link IngestHttpServer}; Slack's HMAC scheme stays HERE as its verify hook,
+ * and this module owns everything after verification.
+ *
+ * Handler order — every gate runs BEFORE the session is touched (skill A8/A46):
+ *   1. POST-only (+ a GET `/slack/health` liveness probe).       [kit]
+ *   2. read the RAW body bytes (size cap) — required for the HMAC. [kit]
+ *   3. signature gate → 401 (verify over the raw bytes, before JSON.parse).
+ *   4. zod-validate the envelope → 400.
+ *   5. `url_verification` → echo `{ challenge }` (the handshake).
+ *   6. dedupe — drop on `X-Slack-Retry-Num` or a seen `event_id`.
+ *   7. drop the bot's own messages (`event.user === botUserId` / `event.bot_id`).
+ *   8. pairing gate — ignore unless the team/channel is authorized.
+ *   9. ACK 200 synchronously, THEN run the turn fire-and-forget (Slack's 3s
+ *      ack budget; never run `runTurn` on the request path).
+ *
+ * Every handler error is caught so a bad request can never escalate to a
+ * process-level uncaughtException.
+ */
+
+const EVENTS_PATH = '/slack/events';
+const HEALTH_PATH = '/slack/health';
+
+/** Decision the channel makes about an inbound event. */
+export interface DispatchContext {
+  readonly teamId: string | undefined;
+  readonly channel: string;
+  readonly text: string;
+  readonly user: string | undefined;
+  readonly threadTs: string;
+  readonly eventType: string;
+}
+
+export interface IngestServerHooks {
+  /** The bot's own user id, captured at start via `auth.test` (drop self-messages). */
+  readonly botUserId: string;
+  /** Is this team/channel authorized to drive the session? (pairing gate) */
+  isAuthorized(teamId: string | undefined, channel: string | undefined): boolean;
+  /**
+   * Observe a verified inbound event from a (possibly unauthorized) team/channel.
+   * Used by the TOFU `pair` flow to capture the first event and persist it.
+   * Returns true if the event was consumed by pairing (so it should NOT also
+   * drive a turn).
+   */
+  onVerifiedEvent?(ev: SlackEventCallback): boolean | Promise<boolean>;
+  /** Run a turn for an authorized, deduped, non-self event (fire-and-forget). */
+  dispatch(ctx: DispatchContext): void;
+}
+
+export interface IngestServerOptions {
+  readonly host?: string;
+  readonly signingSecret: string;
+  readonly hooks: IngestServerHooks;
+  /** Max request body size in bytes. Default 1MB. */
+  readonly maxBodyBytes?: number;
+  /** Override dedupe cache (tests). */
+  readonly dedupe?: DeliveryDedupeCache;
+  readonly logger?: {
+    info?(msg: string, meta?: Record<string, unknown>): void;
+    warn?(msg: string, meta?: Record<string, unknown>): void;
+  };
+}
+
+export type IngestServerHandle = IngestHttpServerHandle;
+
+export class IngestServer {
+  private readonly inner: IngestHttpServer;
+  private readonly dedupe: DeliveryDedupeCache;
+
+  constructor(private readonly opts: IngestServerOptions) {
+    this.dedupe = opts.dedupe ?? new DeliveryDedupeCache();
+    this.inner = new IngestHttpServer({
+      ...(opts.host ? { host: opts.host } : {}),
+      eventsPath: EVENTS_PATH,
+      healthPath: HEALTH_PATH,
+      healthBody: () => ({ status: 'ok', listener: 'slack' }),
+      ...(opts.maxBodyBytes !== undefined ? { maxBodyBytes: opts.maxBodyBytes } : {}),
+      label: 'slack',
+      verify: ({ rawBody, headers }) =>
+        verifySlackSignature({ rawBody, headers, signingSecret: opts.signingSecret }),
+      handleVerified: (raw, req, res) => this.handleVerified(raw, req, res),
+      ...(opts.logger ? { logger: opts.logger } : {}),
+    });
+  }
+
+  get port(): number {
+    return this.inner.port;
+  }
+
+  /** Bind on an ephemeral loopback port. Resolves once listening. */
+  start(): Promise<IngestServerHandle> {
+    return this.inner.start();
+  }
+
+  stop(): Promise<void> {
+    return this.inner.stop();
+  }
+
+  /** Steps 4–9: everything after the raw-body + signature gates. */
+  private async handleVerified(
+    raw: Buffer,
+    req: IncomingMessage,
+    res: ServerResponse,
+  ): Promise<void> {
+    // 4) zod-validate the envelope.
+    let parsedJson: unknown;
+    try {
+      parsedJson = JSON.parse(raw.toString('utf8'));
+    } catch {
+      respondJson(res, 400, { error: 'invalid_json' });
+      return;
+    }
+    const parsed = slackEnvelopeSchema.safeParse(parsedJson);
+    if (!parsed.success) {
+      this.opts.logger?.warn?.('slack: malformed envelope', {
+        issue: parsed.error.issues[0]?.message,
+      });
+      respondJson(res, 400, { error: 'bad_request' });
+      return;
+    }
+    const envelope = parsed.data;
+
+    // 5) url_verification handshake.
+    if (envelope.type === 'url_verification') {
+      respondJson(res, 200, { challenge: envelope.challenge });
+      return;
+    }
+
+    // From here on it's an event_callback. ACK fast; do everything else after
+    // (or fire-and-forget) so we stay inside Slack's 3-second ack budget.
+    const callback = envelope;
+
+    // 6) Dedupe — drop retries / repeated event ids. We record the id only for
+    // verified events so an unverified request can never poison the cache.
+    const isRetry = req.headers['x-slack-retry-num'] !== undefined;
+    const eventId = callback.event_id;
+    const dupe = isRetry || (eventId ? !this.dedupe.check(eventId) : false);
+
+    // 7) Self-message guard: never re-trigger on our own posts.
+    const ev = callback.event;
+    const isSelf =
+      ev.bot_id !== undefined ||
+      (ev.user !== undefined && ev.user === this.opts.hooks.botUserId);
+
+    // ACK synchronously BEFORE running anything.
+    respondJson(res, 200, { status: 'ok' });
+
+    if (dupe || isSelf) return;
+
+    // Pairing TOFU hook gets first crack at a verified event (even unauthorized),
+    // so it can capture + persist the first team/channel.
+    try {
+      const consumed = (await this.opts.hooks.onVerifiedEvent?.(callback)) ?? false;
+      if (consumed) return;
+    } catch (err) {
+      this.opts.logger?.warn?.('slack: pairing hook threw', { err: String(err) });
+    }
+
+    // 8) Pairing gate — only authorized team/channel drives the session.
+    if (!this.opts.hooks.isAuthorized(callback.team_id, ev.channel)) {
+      this.opts.logger?.info?.('slack: dropped event from unauthorized team/channel', {
+        team: callback.team_id,
+        channel: ev.channel,
+      });
+      return;
+    }
+
+    // Only act on message-ish events (we subscribe to app_mention primarily;
+    // message events with an edit/system subtype are ignored).
+    const eventType = ev.type;
+    if (eventType !== 'app_mention' && eventType !== 'message') return;
+    if (ev.subtype) return; // message_changed / message_deleted / channel_join …
+    const channel = ev.channel;
+    const text = (ev.text ?? '').trim();
+    if (!channel || !text) return;
+
+    // 9) Run the turn fire-and-forget (already ACKed).
+    this.opts.hooks.dispatch({
+      teamId: callback.team_id,
+      channel,
+      text,
+      user: ev.user,
+      threadTs: ev.thread_ts ?? ev.ts ?? channel,
+      eventType,
+    });
+  }
+}
+
+export { EVENTS_PATH as SLACK_EVENTS_PATH };

package/src/server/schema.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from 'vitest';
+import { slackEnvelopeSchema, urlVerificationSchema, eventCallbackSchema } from './schema.js';
+
+describe('slack schemas', () => {
+  it('parses a url_verification challenge', () => {
+    const parsed = slackEnvelopeSchema.safeParse({
+      type: 'url_verification',
+      token: 'verif-token',
+      challenge: 'the-challenge-string',
+    });
+    expect(parsed.success).toBe(true);
+    if (parsed.success && parsed.data.type === 'url_verification') {
+      expect(parsed.data.challenge).toBe('the-challenge-string');
+    }
+  });
+
+  it('rejects a url_verification with an empty challenge', () => {
+    const parsed = urlVerificationSchema.safeParse({ type: 'url_verification', challenge: '' });
+    expect(parsed.success).toBe(false);
+  });
+
+  it('parses an app_mention event_callback', () => {
+    const parsed = slackEnvelopeSchema.safeParse({
+      type: 'event_callback',
+      team_id: 'T123',
+      event_id: 'Ev999',
+      event: {
+        type: 'app_mention',
+        user: 'U123',
+        text: '<@UBOT> hello',
+        channel: 'C123',
+        ts: '1700000000.000100',
+      },
+    });
+    expect(parsed.success).toBe(true);
+    if (parsed.success && parsed.data.type === 'event_callback') {
+      expect(parsed.data.event.type).toBe('app_mention');
+      expect(parsed.data.team_id).toBe('T123');
+    }
+  });
+
+  it('rejects a body that is neither handshake nor event_callback', () => {
+    const parsed = slackEnvelopeSchema.safeParse({ type: 'something_else', foo: 1 });
+    expect(parsed.success).toBe(false);
+  });
+
+  it('rejects an event_callback whose event is not an object', () => {
+    const parsed = eventCallbackSchema.safeParse({ type: 'event_callback', event: 'nope' });
+    expect(parsed.success).toBe(false);
+  });
+
+  it('rejects an event_callback missing the inner event type', () => {
+    const parsed = eventCallbackSchema.safeParse({
+      type: 'event_callback',
+      event: { text: 'hi' },
+    });
+    expect(parsed.success).toBe(false);
+  });
+
+  it('tolerates unknown extra fields on the inner event (passthrough)', () => {
+    const parsed = eventCallbackSchema.safeParse({
+      type: 'event_callback',
+      event: { type: 'app_mention', some_future_field: { nested: true } },
+    });
+    expect(parsed.success).toBe(true);
+  });
+});

package/src/server/schema.ts

@@ -0,0 +1,77 @@
+import { z } from '@moxxy/sdk';
+
+/**
+ * zod schemas for the Slack Events API request bodies we accept. Every inbound
+ * body is validated against these BEFORE any field is read or the session is
+ * touched (AGENTS.md A8: validate inbound frames with zod first). Unknown event
+ * subtypes parse to the permissive envelope so we never throw on a Slack event
+ * type we don't subscribe to — we just ignore it.
+ */
+
+/** The URL-verification handshake Slack sends once when you set the Request URL. */
+export const urlVerificationSchema = z.object({
+  type: z.literal('url_verification'),
+  token: z.string().optional(),
+  challenge: z.string().min(1),
+});
+export type SlackUrlVerification = z.infer<typeof urlVerificationSchema>;
+
+/** A `message` or `app_mention` inner event. Loose on the many optional fields. */
+export const messageEventSchema = z.object({
+  type: z.enum(['message', 'app_mention']),
+  /** Author user id. Absent for some bot/system messages. */
+  user: z.string().optional(),
+  /** Set for messages posted by a bot integration (including our own). */
+  bot_id: z.string().optional(),
+  /** Message text (may be empty for attachment-only messages). */
+  text: z.string().optional(),
+  /** Channel the event occurred in. */
+  channel: z.string().optional(),
+  /** Message timestamp (also the thread root when no `thread_ts`). */
+  ts: z.string().optional(),
+  /** Present when the message is inside a thread. */
+  thread_ts: z.string().optional(),
+  /** `message_changed` / `message_deleted` etc. — we ignore edited/system subtypes. */
+  subtype: z.string().optional(),
+});
+export type SlackMessageEvent = z.infer<typeof messageEventSchema>;
+
+/** The `event_callback` envelope wrapping an inner event. */
+export const eventCallbackSchema = z.object({
+  type: z.literal('event_callback'),
+  /** Workspace/team id — the unit we pair against. */
+  team_id: z.string().optional(),
+  api_app_id: z.string().optional(),
+  /** Stable per-event id used for at-least-once dedupe. */
+  event_id: z.string().optional(),
+  event_time: z.number().optional(),
+  /** The actual event. We only act on message/app_mention; others pass through. */
+  event: z
+    .object({
+      type: z.string(),
+      user: z.string().optional(),
+      bot_id: z.string().optional(),
+      text: z.string().optional(),
+      channel: z.string().optional(),
+      ts: z.string().optional(),
+      thread_ts: z.string().optional(),
+      subtype: z.string().optional(),
+    })
+    .passthrough(),
+  /** Bot user ids this event was authorized for — lets us detect self-authored messages. */
+  authorizations: z
+    .array(z.object({ user_id: z.string().optional() }).passthrough())
+    .optional(),
+});
+export type SlackEventCallback = z.infer<typeof eventCallbackSchema>;
+
+/**
+ * The top-level Slack request envelope: either the one-off url_verification
+ * handshake or an event_callback. A discriminated union on `type` so a body
+ * that is neither is rejected with a clear error.
+ */
+export const slackEnvelopeSchema = z.discriminatedUnion('type', [
+  urlVerificationSchema,
+  eventCallbackSchema,
+]);
+export type SlackEnvelope = z.infer<typeof slackEnvelopeSchema>;

package/src/server/verify.test.ts

@@ -0,0 +1,132 @@
+import { createHmac } from 'node:crypto';
+import { describe, expect, it } from 'vitest';
+import { SLACK_REPLAY_WINDOW_SEC, verifySlackSignature } from './verify.js';
+
+const SECRET = 'slack_signing_secret_abcdef0123456789';
+
+/** Build the headers Slack would send for `body` at epoch-seconds `ts`. */
+function sign(body: string, ts: number, secret = SECRET): Record<string, string> {
+  const base = `v0:${ts}:${body}`;
+  const sig = `v0=${createHmac('sha256', secret).update(base).digest('hex')}`;
+  return {
+    'x-slack-request-timestamp': String(ts),
+    'x-slack-signature': sig,
+  };
+}
+
+describe('verifySlackSignature', () => {
+  it('accepts a correctly signed request', () => {
+    const body = '{"type":"event_callback"}';
+    const ts = Math.floor(Date.now() / 1000);
+    const res = verifySlackSignature({
+      rawBody: Buffer.from(body),
+      headers: sign(body, ts),
+      signingSecret: SECRET,
+      nowMs: Date.now(),
+    });
+    expect(res.ok).toBe(true);
+  });
+
+  it('verifies over the RAW bytes (a reserialized body fails)', () => {
+    // The signature is computed over the exact bytes; a body whose JSON has been
+    // reserialized (different whitespace) must not verify.
+    const rawBody = '{"a":1,"b":2}';
+    const ts = Math.floor(Date.now() / 1000);
+    const headers = sign(rawBody, ts);
+    const reserialized = JSON.stringify(JSON.parse(rawBody)); // identical here, so tweak spacing
+    const tweaked = '{ "a": 1, "b": 2 }';
+    expect(reserialized).not.toBe(tweaked);
+    const res = verifySlackSignature({
+      rawBody: Buffer.from(tweaked),
+      headers,
+      signingSecret: SECRET,
+      nowMs: Date.now(),
+    });
+    expect(res.ok).toBe(false);
+  });
+
+  it('rejects a wrong signature', () => {
+    const body = '{"x":1}';
+    const ts = Math.floor(Date.now() / 1000);
+    const headers = sign(body, ts);
+    headers['x-slack-signature'] = 'v0=deadbeef';
+    const res = verifySlackSignature({
+      rawBody: Buffer.from(body),
+      headers,
+      signingSecret: SECRET,
+      nowMs: Date.now(),
+    });
+    expect(res.ok).toBe(false);
+  });
+
+  it('rejects a request signed with a different secret', () => {
+    const body = '{"x":1}';
+    const ts = Math.floor(Date.now() / 1000);
+    const headers = sign(body, ts, 'a-different-secret-entirely');
+    const res = verifySlackSignature({
+      rawBody: Buffer.from(body),
+      headers,
+      signingSecret: SECRET,
+      nowMs: Date.now(),
+    });
+    expect(res.ok).toBe(false);
+  });
+
+  it('rejects a request outside the 5-minute replay window', () => {
+    const body = '{"x":1}';
+    const now = Date.now();
+    const oldTs = Math.floor(now / 1000) - (SLACK_REPLAY_WINDOW_SEC + 10);
+    const res = verifySlackSignature({
+      rawBody: Buffer.from(body),
+      headers: sign(body, oldTs),
+      signingSecret: SECRET,
+      nowMs: now,
+    });
+    expect(res.ok).toBe(false);
+    if (!res.ok) expect(res.reason).toMatch(/replay window/);
+  });
+
+  it('accepts a request at the edge of the replay window', () => {
+    const body = '{"x":1}';
+    const now = Date.now();
+    const edgeTs = Math.floor(now / 1000) - (SLACK_REPLAY_WINDOW_SEC - 5);
+    const res = verifySlackSignature({
+      rawBody: Buffer.from(body),
+      headers: sign(body, edgeTs),
+      signingSecret: SECRET,
+      nowMs: now,
+    });
+    expect(res.ok).toBe(true);
+  });
+
+  it('rejects when headers are missing', () => {
+    const res = verifySlackSignature({
+      rawBody: Buffer.from('{}'),
+      headers: {},
+      signingSecret: SECRET,
+    });
+    expect(res.ok).toBe(false);
+  });
+
+  it('rejects a non-numeric timestamp', () => {
+    const body = '{}';
+    const headers = sign(body, Math.floor(Date.now() / 1000));
+    headers['x-slack-request-timestamp'] = 'not-a-number';
+    const res = verifySlackSignature({
+      rawBody: Buffer.from(body),
+      headers,
+      signingSecret: SECRET,
+    });
+    expect(res.ok).toBe(false);
+  });
+
+  it('rejects when no signing secret is configured', () => {
+    const body = '{}';
+    const res = verifySlackSignature({
+      rawBody: Buffer.from(body),
+      headers: sign(body, Math.floor(Date.now() / 1000)),
+      signingSecret: '',
+    });
+    expect(res.ok).toBe(false);
+  });
+});

package/src/server/verify.ts

@@ -0,0 +1,88 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+
+/**
+ * Slack request-signature verification.
+ *
+ * Slack signs each request with HMAC-SHA256 over the string
+ * `v0:{X-Slack-Request-Timestamp}:{rawBody}`, hex-encoded and prefixed `v0=`,
+ * delivered in the `X-Slack-Signature` header. This is structurally identical
+ * to the Stripe HMAC scheme in `@moxxy/plugin-webhooks/src/verify.ts` — a
+ * timestamped HMAC over the raw bytes with a replay window — so the logic here
+ * mirrors it: verify over the EXACT raw body bytes (never the reserialized
+ * JSON), constant-time compare, and reject deliveries outside a ±5-minute
+ * window to bound replay.
+ *
+ * Always returns a structured verdict; the caller decides whether to log the
+ * reason (useful in dev) or hide it (preferable on a public endpoint).
+ *
+ * See: https://api.slack.com/authentication/verifying-requests-from-slack
+ */
+
+/** Slack's documented replay window: reject requests older than 5 minutes. */
+export const SLACK_REPLAY_WINDOW_SEC = 60 * 5;
+
+export type SlackVerifyResult =
+  | { readonly ok: true }
+  | { readonly ok: false; readonly reason: string };
+
+function lower(
+  headers: Record<string, string | string[] | undefined>,
+  name: string,
+): string | null {
+  const v = headers[name.toLowerCase()];
+  if (Array.isArray(v)) return v[0] ?? null;
+  return v ?? null;
+}
+
+/** Constant-time compare of two `v0=…` hex signatures. */
+function safeEqual(a: string, b: string): boolean {
+  const ab = Buffer.from(a);
+  const bb = Buffer.from(b);
+  if (ab.length !== bb.length) return false;
+  try {
+    return timingSafeEqual(ab, bb);
+  } catch {
+    return false;
+  }
+}
+
+export interface VerifySlackSignatureInput {
+  readonly rawBody: Buffer;
+  readonly headers: Record<string, string | string[] | undefined>;
+  readonly signingSecret: string;
+  /** Epoch-ms used to enforce the replay window. Defaults to `Date.now()`. */
+  readonly nowMs?: number;
+}
+
+/**
+ * Verify a Slack request signature against the raw body. Pass the EXACT bytes
+ * read off the socket, BEFORE `JSON.parse` — reserializing the body changes
+ * whitespace/key-order and breaks the HMAC.
+ */
+export function verifySlackSignature(input: VerifySlackSignatureInput): SlackVerifyResult {
+  const { rawBody, headers, signingSecret } = input;
+  if (!signingSecret) return { ok: false, reason: 'no signing secret configured' };
+
+  const timestamp = lower(headers, 'x-slack-request-timestamp');
+  const signature = lower(headers, 'x-slack-signature');
+  if (!timestamp) return { ok: false, reason: 'missing X-Slack-Request-Timestamp' };
+  if (!signature) return { ok: false, reason: 'missing X-Slack-Signature' };
+
+  const tsNum = Number(timestamp);
+  if (!Number.isFinite(tsNum)) return { ok: false, reason: 'non-numeric timestamp' };
+
+  const now = input.nowMs ?? Date.now();
+  const driftSec = Math.abs(now / 1000 - tsNum);
+  if (driftSec > SLACK_REPLAY_WINDOW_SEC) {
+    return { ok: false, reason: `timestamp drift ${Math.round(driftSec)}s exceeds replay window` };
+  }
+
+  // HMAC over `v0:{ts}:{rawBody}` — note the raw bytes, not a reserialized JSON.
+  const base = Buffer.concat([
+    Buffer.from(`v0:${timestamp}:`, 'utf8'),
+    rawBody,
+  ]);
+  const computed = `v0=${createHmac('sha256', signingSecret).update(base).digest('hex')}`;
+  if (safeEqual(computed, signature)) return { ok: true };
+  return { ok: false, reason: 'signature mismatch' };
+}

package/src/setup-wizard.ts

@@ -0,0 +1,121 @@
+import {
+  cancel,
+  intro,
+  isCancel,
+  log,
+  note,
+  outro,
+  password,
+  spinner,
+  text,
+} from '@clack/prompts';
+import type { ChannelSubcommandContext } from '@moxxy/sdk';
+import type { VaultStore } from '@moxxy/plugin-vault';
+import {
+  SLACK_BOT_TOKEN_KEY,
+  SLACK_BOT_TOKEN_RE,
+  SLACK_SIGNING_SECRET_KEY,
+  slackSigningSecretSchema,
+} from './keys.js';
+import { SlackClient } from './channel/slack-client.js';
+
+const ANSI = process.stdout.isTTY && !process.env.NO_COLOR;
+const bold = (s: string): string => (ANSI ? `\x1b[1m${s}\x1b[22m` : s);
+const dim = (s: string): string => (ANSI ? `\x1b[2m${s}\x1b[22m` : s);
+
+/**
+ * Interactive Slack setup wizard (the channel's `interactiveCommand`).
+ *
+ * Walks the operator through:
+ *   1. paste the bot token (`xoxb-…`) into the vault,
+ *   2. paste the signing secret into the vault,
+ *   3. validate the token via `auth.test`,
+ *   4. choose the working folder + the autonomous tool allow-list,
+ *   5. start the channel (opens the proxy tunnel) and PRINT the public Request
+ *      URL to paste into the Slack app's Event Subscriptions.
+ *
+ * Headless invocations bypass this and start the channel directly (the dispatch
+ * caller decides; this is only reached on a TTY).
+ */
+export async function runSlackWizard(ctx: ChannelSubcommandContext): Promise<number> {
+  const vault = ctx.deps.vault as VaultStore;
+  intro(bold('moxxy slack setup'));
+
+  note(
+    'Create a Slack app at https://api.slack.com/apps → "From scratch".\n' +
+      '• OAuth & Permissions → add the bot scopes app_mentions:read, chat:write,\n' +
+      '  channels:history → Install to Workspace → copy the Bot User OAuth Token (xoxb-…).\n' +
+      '• Basic Information → App Credentials → copy the Signing Secret.\n' +
+      'Both go straight into the moxxy vault — no env vars needed.',
+    'create a Slack app',
+  );
+
+  const token = await password({
+    message: 'Paste the Bot User OAuth Token',
+    mask: '•',
+    validate: (v) => {
+      if (!v || !v.trim()) return 'required';
+      if (!SLACK_BOT_TOKEN_RE.test(v.trim())) return 'expected a token like "xoxb-…"';
+      return undefined;
+    },
+  });
+  if (isCancel(token)) {
+    cancel('cancelled.');
+    return 0;
+  }
+
+  const secret = await password({
+    message: 'Paste the Signing Secret',
+    mask: '•',
+    validate: (v) => {
+      const parsed = slackSigningSecretSchema.safeParse(v);
+      return parsed.success ? undefined : parsed.error.issues[0]?.message ?? 'invalid';
+    },
+  });
+  if (isCancel(secret)) {
+    cancel('cancelled.');
+    return 0;
+  }
+
+  // Validate the token before persisting anything the operator can act on.
+  const spin = spinner();
+  spin.start('Validating the bot token (auth.test)…');
+  try {
+    const client = new SlackClient({ token: String(token).trim() });
+    const auth = await client.authTest();
+    spin.stop(`Token OK — bot user ${auth.botUserId}${auth.team ? ` on ${auth.team}` : ''}.`);
+  } catch (err) {
+    spin.stop('Token validation failed.');
+    log.error(err instanceof Error ? err.message : String(err));
+    return 1;
+  }
+
+  await vault.set(SLACK_BOT_TOKEN_KEY, String(token).trim(), ['slack']);
+  await vault.set(SLACK_SIGNING_SECRET_KEY, String(secret).trim(), ['slack']);
+  log.success('Stored bot token + signing secret in the vault.');
+
+  const allow = await text({
+    message: 'Autonomous tool allow-list (comma-separated; "*" = all, blank = read-only)',
+    placeholder: 'Read, Grep, Glob',
+  });
+  if (isCancel(allow)) {
+    cancel('cancelled.');
+    return 0;
+  }
+  const allowedTools = String(allow)
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+
+  note(
+    'Starting the channel — it opens a proxy tunnel and prints a public Request URL.\n' +
+      'Paste that URL into your Slack app → Event Subscriptions → Request URL, then\n' +
+      'subscribe to the bot event app_mention. Mention the bot in a channel to pair.',
+    'next steps',
+  );
+  log.info('Starting the bot. Press Ctrl+C to stop.');
+  outro(dim('handing off to the channel…'));
+
+  // Start in pairing mode so the first @mention establishes trust automatically.
+  return ctx.startChannel({ pair: true, allowedTools });
+}