@crewhaus/channel-adapter-slack 0.1.4 → 0.1.5

package/dist/index.d.ts

@@ -0,0 +1,105 @@
+/**
+ * @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";
+export { signSlackBody, verifySlackSignature } from "./verify.js";
+export declare class SlackAdapterError extends CrewhausError {
+    readonly name = "SlackAdapterError";
+    constructor(message: string, cause?: unknown);
+}
+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;
+};
+export declare function createSlackAdapter(config: SlackAdapterConfig, opts?: SlackAdapterOptions): ChannelAdapter;

package/dist/index.js

@@ -0,0 +1,164 @@
+/**
+ * @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 {
+    name = "SlackAdapterError";
+    constructor(message, cause) {
+        super("channel", message, cause);
+    }
+}
+const DEFAULT_API_BASE_URL = "https://slack.com/api";
+export function createSlackAdapter(config, opts = {}) {
+    const apiBaseUrl = opts.apiBaseUrl ?? process.env["SLACK_API_BASE_URL"] ?? DEFAULT_API_BASE_URL;
+    const doFetch = opts.fetch ?? fetch;
+    return {
+        id: "slack",
+        verify(req) {
+            return verifySlackSignature({ headers: req.headers, body: req.body, signingSecret: config.signingSecret }, opts.now !== undefined ? { now: opts.now } : {});
+        },
+        parseInbound(req) {
+            let payload;
+            try {
+                payload = JSON.parse(req.body);
+            }
+            catch {
+                return { kind: "skip" };
+            }
+            if (typeof payload !== "object" || payload === null)
+                return { kind: "skip" };
+            const p = payload;
+            // 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;
+            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 = {
+                idempotencyKey,
+                workspaceId,
+                channelId,
+                userId,
+                ...(threadTs !== undefined ? { threadTs } : {}),
+                ts,
+                text,
+                subtype: evType,
+            };
+            return { kind: "event", event };
+        },
+        async sendReply(args) {
+            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());
+                if (body.ok === false) {
+                    throw new SlackAdapterError(`chat.postMessage error: ${body.error ?? "unknown"}`);
+                }
+            }
+        },
+        async setTyping(_args) {
+            // 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) {
+            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());
+                // "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/dist/verify.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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;
+};
+export declare function verifySlackSignature(args: VerifyArgs, opts?: VerifyOptions): boolean;
+/**
+ * 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 declare function signSlackBody(args: {
+    body: string;
+    timestamp: number;
+    signingSecret: string;
+}): string;

package/dist/verify.js

@@ -0,0 +1,31 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+const DEFAULT_TOLERANCE_MS = 5 * 60 * 1000;
+export function verifySlackSignature(args, opts = {}) {
+    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) {
+    const base = `v0:${args.timestamp}:${args.body}`;
+    return `v0=${createHmac("sha256", args.signingSecret).update(base).digest("hex")}`;
+}

package/package.json

@@ -1,18 +1,21 @@
 {
   "name": "@crewhaus/channel-adapter-slack",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "type": "module",
   "description": "Slack channel adapter: webhook signature verification, event parsing, reply-to-thread (Section 12)",
-  "main": "src/index.ts",
-  "types": "src/index.ts",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
   },
   "scripts": {
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/errors": "0.1.4"
+    "@crewhaus/errors": "0.1.5"
   },
   "license": "Apache-2.0",
   "author": {
@@ -32,5 +35,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "files": ["src", "README.md", "LICENSE", "NOTICE"]
+  "files": ["dist", "README.md", "LICENSE", "NOTICE"]
 }

package/src/fixtures/app_mention.json

@@ -1,18 +0,0 @@
-{
-  "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

@@ -1,17 +0,0 @@
-{
-  "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

@@ -1,17 +0,0 @@
-{
-  "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

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