@crewhaus/channel-adapter-slack 0.1.0

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@crewhaus/channel-adapter-slack",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Slack channel adapter: webhook signature verification, event parsing, reply-to-thread (Section 12)",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@crewhaus/errors": "0.0.0"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Max Meier",
+    "email": "max@studiomax.io",
+    "url": "https://studiomax.io"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crewhaus/factory.git",
+    "directory": "packages/channel-adapter-slack"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/channel-adapter-slack#readme",
+  "bugs": {
+    "url": "https://github.com/crewhaus/factory/issues"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ]
+}

package/src/fixtures/app_mention.json

@@ -0,0 +1,18 @@
+{
+  "token": "Vt9PuruQ8XWLn8eK",
+  "team_id": "T12345WRK",
+  "api_app_id": "A0KRDEXAMPLE",
+  "event": {
+    "type": "app_mention",
+    "user": "U07USER01",
+    "text": "<@U0BOT> what time is it?",
+    "ts": "1700000000.000100",
+    "channel": "C0CHAN01",
+    "event_ts": "1700000000.000100",
+    "thread_ts": "1700000000.000100"
+  },
+  "type": "event_callback",
+  "event_id": "Ev0EVENTONE",
+  "event_time": 1700000000,
+  "authorizations": []
+}

package/src/fixtures/bot_message.json

@@ -0,0 +1,17 @@
+{
+  "token": "Vt9PuruQ8XWLn8eK",
+  "team_id": "T12345WRK",
+  "api_app_id": "A0KRDEXAMPLE",
+  "event": {
+    "type": "message",
+    "subtype": "bot_message",
+    "bot_id": "B0BOT01",
+    "text": "hello",
+    "ts": "1700000002.000300",
+    "channel": "C0CHAN01"
+  },
+  "type": "event_callback",
+  "event_id": "Ev0EVENTTHREE",
+  "event_time": 1700000002,
+  "authorizations": []
+}

package/src/fixtures/message.json

@@ -0,0 +1,17 @@
+{
+  "token": "Vt9PuruQ8XWLn8eK",
+  "team_id": "T12345WRK",
+  "api_app_id": "A0KRDEXAMPLE",
+  "event": {
+    "type": "message",
+    "user": "U07USER01",
+    "text": "ping",
+    "ts": "1700000001.000200",
+    "channel": "C0CHAN01",
+    "event_ts": "1700000001.000200"
+  },
+  "type": "event_callback",
+  "event_id": "Ev0EVENTTWO",
+  "event_time": 1700000001,
+  "authorizations": []
+}

package/src/fixtures/url_verification.json

@@ -0,0 +1,5 @@
+{
+  "token": "Jhj5dZrVaK7ZwHHjRyZWjbDl",
+  "challenge": "3eZbrw1aBm2rZgRNFdxV2595E9CY3gmdALWMmHkvFXO7tYXAYM8P",
+  "type": "url_verification"
+}

package/src/index.test.ts

@@ -0,0 +1,365 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { createSlackAdapter, signSlackBody, verifySlackSignature } from "./index";
+
+// `tsc -b` also compiles this file into `dist/`; resolve fixtures from the
+// source tree so both the src and dist test copies find them.
+const FIXTURES = join(import.meta.dir.replace(/([/\\])dist$/, "$1src"), "fixtures");
+const APP_MENTION = readFileSync(join(FIXTURES, "app_mention.json"), "utf8");
+const MESSAGE = readFileSync(join(FIXTURES, "message.json"), "utf8");
+const BOT_MESSAGE = readFileSync(join(FIXTURES, "bot_message.json"), "utf8");
+const URL_VERIFICATION = readFileSync(join(FIXTURES, "url_verification.json"), "utf8");
+
+const SECRET = "test-secret-1234567890";
+
+function signedHeaders(body: string, secret: string, ts: number = Math.floor(Date.now() / 1000)) {
+  const headers = new Headers();
+  headers.set("x-slack-request-timestamp", String(ts));
+  headers.set("x-slack-signature", signSlackBody({ body, timestamp: ts, signingSecret: secret }));
+  return headers;
+}
+
+describe("verifySlackSignature (T8 — security)", () => {
+  test("accepts a freshly signed request", () => {
+    const body = APP_MENTION;
+    const headers = signedHeaders(body, SECRET);
+    expect(verifySlackSignature({ headers, body, signingSecret: SECRET })).toBe(true);
+  });
+
+  test("rejects a request with a tampered body", () => {
+    const headers = signedHeaders(APP_MENTION, SECRET);
+    const tamperedBody = APP_MENTION.replace("what time is it?", "rm -rf");
+    expect(verifySlackSignature({ headers, body: tamperedBody, signingSecret: SECRET })).toBe(
+      false,
+    );
+  });
+
+  test("rejects a request with a tampered signature", () => {
+    const body = APP_MENTION;
+    const headers = signedHeaders(body, SECRET);
+    headers.set(
+      "x-slack-signature",
+      `${headers.get("x-slack-signature")?.slice(0, -2) ?? "v0="}00`,
+    );
+    expect(verifySlackSignature({ headers, body, signingSecret: SECRET })).toBe(false);
+  });
+
+  test("rejects a request signed with a different secret", () => {
+    const body = APP_MENTION;
+    const headers = signedHeaders(body, "wrong-secret");
+    expect(verifySlackSignature({ headers, body, signingSecret: SECRET })).toBe(false);
+  });
+
+  test("rejects a request with an expired timestamp (replay attack)", () => {
+    const body = APP_MENTION;
+    const oldTs = Math.floor(Date.now() / 1000) - 10 * 60; // 10 minutes ago
+    const headers = signedHeaders(body, SECRET, oldTs);
+    expect(verifySlackSignature({ headers, body, signingSecret: SECRET })).toBe(false);
+  });
+
+  test("rejects a request with a future timestamp", () => {
+    const body = APP_MENTION;
+    const futureTs = Math.floor(Date.now() / 1000) + 10 * 60;
+    const headers = signedHeaders(body, SECRET, futureTs);
+    expect(verifySlackSignature({ headers, body, signingSecret: SECRET })).toBe(false);
+  });
+
+  test("rejects a request with missing timestamp header", () => {
+    const body = APP_MENTION;
+    const headers = signedHeaders(body, SECRET);
+    headers.delete("x-slack-request-timestamp");
+    expect(verifySlackSignature({ headers, body, signingSecret: SECRET })).toBe(false);
+  });
+
+  test("rejects a request with missing signature header", () => {
+    const body = APP_MENTION;
+    const headers = signedHeaders(body, SECRET);
+    headers.delete("x-slack-signature");
+    expect(verifySlackSignature({ headers, body, signingSecret: SECRET })).toBe(false);
+  });
+
+  test("rejects a request with a malformed (non-numeric) timestamp", () => {
+    const body = APP_MENTION;
+    const headers = signedHeaders(body, SECRET);
+    headers.set("x-slack-request-timestamp", "not-a-number");
+    expect(verifySlackSignature({ headers, body, signingSecret: SECRET })).toBe(false);
+  });
+
+  test("rejects a request whose signature has the wrong length (timing-safe equal guard)", () => {
+    const body = APP_MENTION;
+    const headers = signedHeaders(body, SECRET);
+    headers.set("x-slack-signature", "v0=short");
+    expect(verifySlackSignature({ headers, body, signingSecret: SECRET })).toBe(false);
+  });
+
+  test("honours an injected `now` for tolerance testing", () => {
+    const body = APP_MENTION;
+    const fixedTs = 1700000000;
+    const headers = signedHeaders(body, SECRET, fixedTs);
+    const stillFresh = verifySlackSignature(
+      { headers, body, signingSecret: SECRET },
+      { now: () => fixedTs * 1000 + 60_000 },
+    );
+    expect(stillFresh).toBe(true);
+    const stale = verifySlackSignature(
+      { headers, body, signingSecret: SECRET },
+      { now: () => fixedTs * 1000 + 10 * 60_000 },
+    );
+    expect(stale).toBe(false);
+  });
+});
+
+describe("createSlackAdapter — parseInbound (T2 — contract)", () => {
+  function adapter() {
+    return createSlackAdapter({ botToken: "xoxb-test", signingSecret: SECRET });
+  }
+
+  test("parses app_mention into a normalised InboundEvent", () => {
+    const out = adapter().parseInbound({ headers: new Headers(), body: APP_MENTION });
+    expect(out.kind).toBe("event");
+    if (out.kind !== "event") return;
+    expect(out.event.subtype).toBe("app_mention");
+    expect(out.event.workspaceId).toBe("T12345WRK");
+    expect(out.event.channelId).toBe("C0CHAN01");
+    expect(out.event.userId).toBe("U07USER01");
+    expect(out.event.text).toBe("<@U0BOT> what time is it?");
+    expect(out.event.threadTs).toBe("1700000000.000100");
+    expect(out.event.idempotencyKey).toBe("Ev0EVENTONE");
+  });
+
+  test("parses a top-level message event", () => {
+    const out = adapter().parseInbound({ headers: new Headers(), body: MESSAGE });
+    expect(out.kind).toBe("event");
+    if (out.kind !== "event") return;
+    expect(out.event.subtype).toBe("message");
+    expect(out.event.threadTs).toBeUndefined();
+    expect(out.event.text).toBe("ping");
+  });
+
+  test("skips bot self-mentions (subtype: bot_message)", () => {
+    const out = adapter().parseInbound({ headers: new Headers(), body: BOT_MESSAGE });
+    expect(out.kind).toBe("skip");
+  });
+
+  test("returns a challenge for url_verification", () => {
+    const out = adapter().parseInbound({ headers: new Headers(), body: URL_VERIFICATION });
+    expect(out.kind).toBe("challenge");
+    if (out.kind !== "challenge") return;
+    expect(out.challenge.length).toBeGreaterThan(0);
+  });
+
+  test("skips unparsable JSON", () => {
+    const out = adapter().parseInbound({ headers: new Headers(), body: "not-json" });
+    expect(out.kind).toBe("skip");
+  });
+
+  test("skips events outside the {app_mention, message} set", () => {
+    const body = JSON.stringify({
+      type: "event_callback",
+      team_id: "T1",
+      event_id: "E1",
+      event: { type: "channel_created", channel: "C1", user: "U1", ts: "1.0" },
+    });
+    const out = adapter().parseInbound({ headers: new Headers(), body });
+    expect(out.kind).toBe("skip");
+  });
+
+  test("skips events with another bot's bot_id when selfBotId is unspecified", () => {
+    const body = JSON.stringify({
+      type: "event_callback",
+      team_id: "T1",
+      event_id: "E1",
+      event: {
+        type: "message",
+        bot_id: "B_OTHER",
+        text: "hi",
+        channel: "C1",
+        user: "U1",
+        ts: "1.0",
+      },
+    });
+    const out = adapter().parseInbound({ headers: new Headers(), body });
+    expect(out.kind).toBe("skip");
+  });
+});
+
+describe("createSlackAdapter — sendReply", () => {
+  test("POSTs chat.postMessage with channel/thread_ts/text", async () => {
+    const captured: Array<{ url: string; body: string; auth: string }> = [];
+    const fakeFetch: typeof fetch = (async (input: string | URL | Request, init?: RequestInit) => {
+      const url = typeof input === "string" ? input : input.toString();
+      captured.push({
+        url,
+        body: typeof init?.body === "string" ? init.body : "",
+        auth: (init?.headers as Record<string, string>)["Authorization"] ?? "",
+      });
+      return new Response(JSON.stringify({ ok: true }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      });
+    }) as unknown as typeof fetch;
+
+    const adapter = createSlackAdapter(
+      { botToken: "xoxb-rotated", signingSecret: SECRET },
+      { apiBaseUrl: "https://slack.test/api", fetch: fakeFetch },
+    );
+
+    await adapter.sendReply({
+      event: {
+        idempotencyKey: "E1",
+        workspaceId: "T1",
+        channelId: "C1",
+        userId: "U1",
+        threadTs: "1.0",
+        ts: "1.1",
+        text: "hi",
+        subtype: "app_mention",
+      },
+      text: "hello back",
+    });
+
+    expect(captured.length).toBe(1);
+    expect(captured[0]?.url).toBe("https://slack.test/api/chat.postMessage");
+    expect(captured[0]?.auth).toBe("Bearer xoxb-rotated");
+    const body = JSON.parse(captured[0]?.body ?? "{}");
+    expect(body.channel).toBe("C1");
+    expect(body.thread_ts).toBe("1.0");
+    expect(body.text).toBe("hello back");
+  });
+
+  test("falls back to event.ts when no threadTs is set", async () => {
+    let captured: { thread_ts?: string } = {};
+    const fakeFetch: typeof fetch = (async (_input: string | URL | Request, init?: RequestInit) => {
+      captured = JSON.parse(typeof init?.body === "string" ? init.body : "{}");
+      return new Response(JSON.stringify({ ok: true }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      });
+    }) as unknown as typeof fetch;
+
+    const adapter = createSlackAdapter(
+      { botToken: "xoxb", signingSecret: SECRET },
+      { fetch: fakeFetch },
+    );
+    await adapter.sendReply({
+      event: {
+        idempotencyKey: "E",
+        workspaceId: "T",
+        channelId: "C",
+        userId: "U",
+        ts: "9.9",
+        text: "x",
+        subtype: "message",
+      },
+      text: "out",
+    });
+    expect(captured.thread_ts).toBe("9.9");
+  });
+
+  test("throws on Slack ok:false response", async () => {
+    const fakeFetch: typeof fetch = (async () =>
+      new Response(JSON.stringify({ ok: false, error: "channel_not_found" }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      })) as unknown as typeof fetch;
+
+    const adapter = createSlackAdapter(
+      { botToken: "xoxb", signingSecret: SECRET },
+      { fetch: fakeFetch },
+    );
+    await expect(
+      adapter.sendReply({
+        event: {
+          idempotencyKey: "E",
+          workspaceId: "T",
+          channelId: "C",
+          userId: "U",
+          ts: "1.0",
+          text: "x",
+          subtype: "message",
+        },
+        text: "x",
+      }),
+    ).rejects.toThrow(/channel_not_found/);
+  });
+});
+
+describe("react (Phase 3 §3.2)", () => {
+  const sampleEvent = {
+    idempotencyKey: "E1",
+    workspaceId: "T1",
+    channelId: "C1",
+    userId: "U1",
+    ts: "1234.5678",
+    text: "hello",
+    subtype: "message" as const,
+  };
+
+  test("posts to reactions.add with channel + timestamp + emoji name", async () => {
+    let capturedUrl = "";
+    let capturedBody = "";
+    const fakeFetch: typeof fetch = async (url, init) => {
+      capturedUrl = String(url);
+      capturedBody = String(init?.body ?? "");
+      return new Response(JSON.stringify({ ok: true }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      });
+    };
+    const adapter = createSlackAdapter(
+      { botToken: "xoxb-test", signingSecret: SECRET },
+      { fetch: fakeFetch },
+    );
+    expect(adapter.react).toBeDefined();
+    await adapter.react?.({ event: sampleEvent, emoji: "eyes" });
+    expect(capturedUrl).toBe("https://slack.com/api/reactions.add");
+    const body = JSON.parse(capturedBody) as { channel: string; timestamp: string; name: string };
+    expect(body.channel).toBe("C1");
+    expect(body.timestamp).toBe("1234.5678");
+    expect(body.name).toBe("eyes");
+  });
+
+  test("strips leading/trailing colons from emoji name", async () => {
+    let capturedBody = "";
+    const fakeFetch: typeof fetch = async (_url, init) => {
+      capturedBody = String(init?.body ?? "");
+      return new Response(JSON.stringify({ ok: true }), { status: 200 });
+    };
+    const adapter = createSlackAdapter(
+      { botToken: "xoxb", signingSecret: SECRET },
+      { fetch: fakeFetch },
+    );
+    await adapter.react?.({ event: sampleEvent, emoji: ":white_check_mark:" });
+    const body = JSON.parse(capturedBody) as { name: string };
+    expect(body.name).toBe("white_check_mark");
+  });
+
+  test("treats already_reacted as benign no-op", async () => {
+    const fakeFetch: typeof fetch = async () =>
+      new Response(JSON.stringify({ ok: false, error: "already_reacted" }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      });
+    const adapter = createSlackAdapter(
+      { botToken: "xoxb", signingSecret: SECRET },
+      { fetch: fakeFetch },
+    );
+    await expect(adapter.react?.({ event: sampleEvent, emoji: "eyes" })).resolves.toBeUndefined();
+  });
+
+  test("throws on non-already_reacted error", async () => {
+    const fakeFetch: typeof fetch = async () =>
+      new Response(JSON.stringify({ ok: false, error: "invalid_auth" }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      });
+    const adapter = createSlackAdapter(
+      { botToken: "xoxb", signingSecret: SECRET },
+      { fetch: fakeFetch },
+    );
+    await expect(adapter.react?.({ event: sampleEvent, emoji: "eyes" })).rejects.toThrow(
+      /invalid_auth/,
+    );
+  });
+});

package/src/index.ts

@@ -0,0 +1,249 @@
+/**
+ * @crewhaus/channel-adapter-slack — Slack channel adapter for the channel
+ * target (Section 12).
+ *
+ * Implements the `ChannelAdapter` contract:
+ *   verify(req)        — HMAC-SHA256 of `v0:${ts}:${body}` against
+ *                        X-Slack-Signature, with a ±5 min replay window
+ *   parseInbound(req)  — normalises Slack `event_callback` envelopes into
+ *                        a flat `InboundEvent`. Returns null for
+ *                        url_verification, bot self-mentions, and types
+ *                        outside `app_mention` / `message`.
+ *   sendReply(args)    — POSTs `chat.postMessage` with a Bearer token; the
+ *                        api base URL is overridable via constructor opt
+ *                        (or `SLACK_API_BASE_URL` env) so tests can mock it.
+ *   setTyping(args)    — no-op placeholder (Slack has no public typing API).
+ *
+ * The adapter is idempotency-key-aware (Section 12 design review): it
+ * surfaces the inbound `event_id` so the channel-generic gateway can dedup
+ * Slack retries without coupling the gateway to Slack-specific terminology.
+ *
+ * No `@slack/*` SDK dependency — Slack's HTTP API is plain JSON, and Node's
+ * built-in `crypto` covers HMAC. Keeps the bundle slim and the trust
+ * surface minimal.
+ */
+import { CrewhausError } from "@crewhaus/errors";
+import { signSlackBody, verifySlackSignature } from "./verify.js";
+
+export { signSlackBody, verifySlackSignature } from "./verify.js";
+
+export class SlackAdapterError extends CrewhausError {
+  override readonly name = "SlackAdapterError";
+  constructor(message: string, cause?: unknown) {
+    super("channel", message, cause);
+  }
+}
+
+export type RawRequest = {
+  readonly headers: Headers;
+  readonly body: string;
+};
+
+/**
+ * Channel-generic inbound event. The adapter normalises every channel's
+ * native payload (Slack `event_callback`, future Telegram update, etc.)
+ * into this flat shape. The gateway and session-router never see the raw
+ * payload — they only see this.
+ */
+export type InboundEvent = {
+  readonly idempotencyKey: string;
+  readonly workspaceId: string;
+  readonly channelId: string;
+  readonly userId: string;
+  readonly threadTs?: string;
+  readonly ts: string;
+  readonly text: string;
+  readonly subtype: "app_mention" | "message";
+};
+
+/**
+ * The result of `parseInbound`. Three shapes:
+ *   - { kind: "event", event } — a real inbound message to route
+ *   - { kind: "challenge", challenge } — Slack URL-verification handshake;
+ *     gateway responds with the challenge string in plaintext
+ *   - { kind: "skip" } — known-but-uninteresting payload (bot self-mention,
+ *     non-message event types, etc.); gateway responds 200 and moves on
+ */
+export type ParsedInbound =
+  | { readonly kind: "event"; readonly event: InboundEvent }
+  | { readonly kind: "challenge"; readonly challenge: string }
+  | { readonly kind: "skip" };
+
+export interface ChannelAdapter {
+  readonly id: string;
+  verify(req: RawRequest): boolean;
+  parseInbound(req: RawRequest): ParsedInbound;
+  sendReply(args: { event: InboundEvent; text: string }): Promise<void>;
+  setTyping(args: { event: InboundEvent }): Promise<void>;
+  /**
+   * Phase 3 §3.2 — add an emoji reaction to an inbound message as a
+   * lightweight status acknowledgement. Conventionally:
+   *   - "eyes" (👀) on pre-tool / start
+   *   - "white_check_mark" (✅) on post-tool / success
+   *   - "warning" (⚠️) on need-approval / error
+   * Optional — adapters that don't support reactions (or haven't
+   * implemented yet) can leave this undefined and the runtime will
+   * skip the hook silently.
+   */
+  react?(args: { event: InboundEvent; emoji: string }): Promise<void>;
+}
+
+export type SlackAdapterConfig = {
+  readonly botToken: string;
+  readonly signingSecret: string;
+  readonly appToken?: string;
+};
+
+export type SlackAdapterOptions = {
+  readonly apiBaseUrl?: string;
+  readonly fetch?: typeof fetch;
+  readonly now?: () => number;
+  readonly selfBotId?: string;
+};
+
+const DEFAULT_API_BASE_URL = "https://slack.com/api";
+
+export function createSlackAdapter(
+  config: SlackAdapterConfig,
+  opts: SlackAdapterOptions = {},
+): ChannelAdapter {
+  const apiBaseUrl = opts.apiBaseUrl ?? process.env["SLACK_API_BASE_URL"] ?? DEFAULT_API_BASE_URL;
+  const doFetch = opts.fetch ?? fetch;
+
+  return {
+    id: "slack",
+
+    verify(req: RawRequest): boolean {
+      return verifySlackSignature(
+        { headers: req.headers, body: req.body, signingSecret: config.signingSecret },
+        opts.now !== undefined ? { now: opts.now } : {},
+      );
+    },
+
+    parseInbound(req: RawRequest): ParsedInbound {
+      let payload: unknown;
+      try {
+        payload = JSON.parse(req.body);
+      } catch {
+        return { kind: "skip" };
+      }
+      if (typeof payload !== "object" || payload === null) return { kind: "skip" };
+      const p = payload as Record<string, unknown>;
+
+      // URL-verification handshake (Slack sends this once when you point an
+      // app's Event Subscription at a new URL).
+      if (p["type"] === "url_verification" && typeof p["challenge"] === "string") {
+        return { kind: "challenge", challenge: p["challenge"] };
+      }
+
+      if (p["type"] !== "event_callback") return { kind: "skip" };
+
+      const ev = p["event"];
+      if (typeof ev !== "object" || ev === null) return { kind: "skip" };
+      const e = ev as Record<string, unknown>;
+
+      const evType = e["type"];
+      if (evType !== "app_mention" && evType !== "message") return { kind: "skip" };
+
+      // Skip self/bot loops. `bot_id` is present on Slack's bot-authored
+      // messages; `subtype: bot_message` is the older convention.
+      if (typeof e["bot_id"] === "string") {
+        if (opts.selfBotId === undefined || e["bot_id"] === opts.selfBotId) {
+          return { kind: "skip" };
+        }
+      }
+      if (e["subtype"] === "bot_message") return { kind: "skip" };
+
+      const idempotencyKey = typeof p["event_id"] === "string" ? p["event_id"] : undefined;
+      const workspaceId = typeof p["team_id"] === "string" ? p["team_id"] : undefined;
+      const channelId = typeof e["channel"] === "string" ? e["channel"] : undefined;
+      const userId = typeof e["user"] === "string" ? e["user"] : undefined;
+      const ts = typeof e["ts"] === "string" ? e["ts"] : undefined;
+      const text = typeof e["text"] === "string" ? e["text"] : "";
+      const threadTs = typeof e["thread_ts"] === "string" ? e["thread_ts"] : undefined;
+
+      if (!idempotencyKey || !workspaceId || !channelId || !userId || !ts) {
+        return { kind: "skip" };
+      }
+
+      const event: InboundEvent = {
+        idempotencyKey,
+        workspaceId,
+        channelId,
+        userId,
+        ...(threadTs !== undefined ? { threadTs } : {}),
+        ts,
+        text,
+        subtype: evType,
+      };
+      return { kind: "event", event };
+    },
+
+    async sendReply(args: { event: InboundEvent; text: string }): Promise<void> {
+      const url = `${apiBaseUrl}/chat.postMessage`;
+      const threadKey = args.event.threadTs ?? args.event.ts;
+      const res = await doFetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json; charset=utf-8",
+          Authorization: `Bearer ${config.botToken}`,
+        },
+        body: JSON.stringify({
+          channel: args.event.channelId,
+          thread_ts: threadKey,
+          text: args.text,
+        }),
+      });
+      if (!res.ok) {
+        throw new SlackAdapterError(`chat.postMessage failed: ${res.status} ${res.statusText}`);
+      }
+      // Slack returns { ok: false } at HTTP 200 on logical errors; surface that.
+      const ct = res.headers.get("content-type") ?? "";
+      if (ct.includes("application/json")) {
+        const body = (await res.json()) as { ok?: boolean; error?: string };
+        if (body.ok === false) {
+          throw new SlackAdapterError(`chat.postMessage error: ${body.error ?? "unknown"}`);
+        }
+      }
+    },
+
+    async setTyping(_args: { event: InboundEvent }): Promise<void> {
+      // Slack has no public typing-indicator API for bots. No-op for v0;
+      // future versions may use the `assistant.threads.setStatus` API
+      // (Slack AI Assistant beta) for an approximation.
+    },
+
+    // Phase 3 §3.2 — emoji reactions via reactions.add.
+    // Slack expects emoji names without colons ("eyes", not ":eyes:").
+    async react(args: { event: InboundEvent; emoji: string }): Promise<void> {
+      const emoji = args.emoji.replace(/^:|:$/g, "");
+      const url = `${apiBaseUrl}/reactions.add`;
+      const res = await doFetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json; charset=utf-8",
+          Authorization: `Bearer ${config.botToken}`,
+        },
+        body: JSON.stringify({
+          channel: args.event.channelId,
+          timestamp: args.event.ts,
+          name: emoji,
+        }),
+      });
+      if (!res.ok) {
+        // Reactions are best-effort — log via thrown error but the
+        // session-router catches and continues so a flaky API doesn't
+        // abort message processing.
+        throw new SlackAdapterError(`reactions.add failed: ${res.status} ${res.statusText}`);
+      }
+      const ct = res.headers.get("content-type") ?? "";
+      if (ct.includes("application/json")) {
+        const body = (await res.json()) as { ok?: boolean; error?: string };
+        // "already_reacted" is a benign no-op; don't surface as error.
+        if (body.ok === false && body.error !== "already_reacted") {
+          throw new SlackAdapterError(`reactions.add error: ${body.error ?? "unknown"}`);
+        }
+      }
+    },
+  };
+}

package/src/verify.ts

@@ -0,0 +1,63 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+/**
+ * Verify a Slack webhook signature per
+ * https://api.slack.com/authentication/verifying-requests-from-slack.
+ *
+ * Signing-base string is `v0:${timestamp}:${body}`. HMAC-SHA256 with the
+ * signing secret, hex-encoded, with `v0=` prefix. Compared via
+ * `timingSafeEqual` (constant-time, prevents nibble-leak side channels).
+ *
+ * The 5-minute timestamp tolerance is the Slack-recommended replay-window
+ * cap; without it a captured signed payload could be re-played indefinitely.
+ *
+ * Returns false on missing headers, malformed timestamp, mismatched
+ * signature, or stale/future timestamp.
+ */
+export type VerifyArgs = {
+  readonly headers: Headers;
+  readonly body: string;
+  readonly signingSecret: string;
+};
+
+export type VerifyOptions = {
+  readonly now?: () => number;
+  readonly toleranceMs?: number;
+};
+
+const DEFAULT_TOLERANCE_MS = 5 * 60 * 1000;
+
+export function verifySlackSignature(args: VerifyArgs, opts: VerifyOptions = {}): boolean {
+  const now = opts.now ?? (() => Date.now());
+  const tolerance = opts.toleranceMs ?? DEFAULT_TOLERANCE_MS;
+
+  const timestamp = args.headers.get("x-slack-request-timestamp");
+  const signature = args.headers.get("x-slack-signature");
+  if (!timestamp || !signature) return false;
+
+  const tsNum = Number.parseInt(timestamp, 10);
+  if (!Number.isFinite(tsNum)) return false;
+  if (Math.abs(now() - tsNum * 1000) > tolerance) return false;
+
+  const base = `v0:${timestamp}:${args.body}`;
+  const expected = `v0=${createHmac("sha256", args.signingSecret).update(base).digest("hex")}`;
+
+  const expectedBuf = Buffer.from(expected, "utf8");
+  const actualBuf = Buffer.from(signature, "utf8");
+  if (expectedBuf.length !== actualBuf.length) return false;
+  return timingSafeEqual(expectedBuf, actualBuf);
+}
+
+/**
+ * Compute a valid `X-Slack-Signature` for a body — used by smoke tests and
+ * the in-repo integration test to construct fixtures the daemon will accept.
+ * Production code should NEVER call this — Slack signs requests, not us.
+ */
+export function signSlackBody(args: {
+  body: string;
+  timestamp: number;
+  signingSecret: string;
+}): string {
+  const base = `v0:${args.timestamp}:${args.body}`;
+  return `v0=${createHmac("sha256", args.signingSecret).update(base).digest("hex")}`;
+}