@crewhaus/channel-adapter-discord 0.1.3 → 0.1.5

package/dist/index.d.ts

@@ -0,0 +1,132 @@
+/**
+ * @crewhaus/channel-adapter-discord — Discord channel adapter for the
+ * channel target (Section 33).
+ *
+ * Discord's interaction model is request/response: the bot is invoked
+ * via slash commands (interaction type 2), button clicks (type 3), and
+ * modal submits (type 5). Each request is Ed25519-signed via
+ * `X-Signature-Ed25519` + `X-Signature-Timestamp`.
+ *
+ * Discord requires the bot to respond *to the request itself* — the
+ * gateway POSTs the interaction-response body back. For backward
+ * compatibility with the channel adapter contract, `sendReply` instead
+ * uses Discord's "follow-up message" API (`POST /webhooks/{appId}/{token}`)
+ * which works at any time after the initial deferred response.
+ *
+ * Thread session keying uses Discord's native `thread_id` when present
+ * (forum / public thread / archived thread); otherwise the channel id.
+ */
+import { CrewhausError } from "@crewhaus/errors";
+export { generateEd25519Keypair, signDiscordBody, verifyDiscordSignature, } from "./verify.js";
+export declare class DiscordAdapterError extends CrewhausError {
+    readonly name = "DiscordAdapterError";
+    constructor(message: string, cause?: unknown);
+}
+export type RawRequest = {
+    readonly headers: Headers;
+    readonly body: string;
+};
+/**
+ * Channel-generic inbound event. Same shape as Slack/Telegram:
+ *
+ * Mappings:
+ *   - workspaceId   → guild_id (or "dm" when not in a guild)
+ *   - channelId     → channel_id
+ *   - userId        → user.id (or member.user.id in guild context)
+ *   - threadTs      → channel_id when the channel is a thread
+ *   - ts            → interaction id (snowflake; monotonic-ish)
+ *   - text          → command-name + options for slash commands;
+ *                     custom_id for component clicks; modal field values
+ *                     joined for modal submits
+ *   - subtype       → "message" | "app_mention"
+ *   - idempotencyKey → interaction id (Discord doesn't redeliver, but we
+ *                      surface the id so the gateway dedups consistently)
+ */
+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";
+};
+export type ParsedInbound = {
+    readonly kind: "event";
+    readonly event: InboundEvent;
+}
+/**
+ * Discord pings every interactions endpoint with a `type:1` PING that
+ * must be answered with `type:1` PONG before any real interactions
+ * arrive. The gateway responds with the canned PONG body.
+ */
+ | {
+    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>;
+}
+export type DiscordAdapterConfig = {
+    /** Application id (snowflake). Used by the follow-up webhook URL. */
+    readonly applicationId: string;
+    /** Bot user token — used to authorize follow-up REST calls. */
+    readonly botToken: string;
+    /** Public key (hex, 64 chars) for Ed25519 verification. */
+    readonly publicKeyHex: string;
+};
+export type DiscordAdapterOptions = {
+    readonly apiBaseUrl?: string;
+    readonly fetch?: typeof fetch;
+    /** Clock injection for the signature replay-window check (tests). */
+    readonly now?: () => number;
+};
+export declare function createDiscordAdapter(config: DiscordAdapterConfig, opts?: DiscordAdapterOptions): ChannelAdapter;
+export type DiscordInteraction = {
+    readonly id: string;
+    readonly application_id?: string;
+    readonly type: number;
+    readonly token?: string;
+    readonly channel_id?: string;
+    readonly guild_id?: string;
+    readonly user?: {
+        readonly id: string;
+        readonly username?: string;
+    };
+    readonly member?: {
+        readonly user?: {
+            readonly id: string;
+            readonly username?: string;
+        };
+    };
+    readonly channel?: {
+        readonly id?: string;
+        readonly parent_id?: string;
+    };
+    readonly data?: {
+        readonly name?: string;
+        readonly custom_id?: string;
+        readonly options?: ReadonlyArray<{
+            readonly name: string;
+            readonly value?: unknown;
+        }>;
+        readonly components?: ReadonlyArray<{
+            readonly components?: ReadonlyArray<{
+                readonly custom_id?: string;
+                readonly value?: string;
+            }>;
+        }>;
+    };
+};

package/dist/index.js

@@ -0,0 +1,165 @@
+/**
+ * @crewhaus/channel-adapter-discord — Discord channel adapter for the
+ * channel target (Section 33).
+ *
+ * Discord's interaction model is request/response: the bot is invoked
+ * via slash commands (interaction type 2), button clicks (type 3), and
+ * modal submits (type 5). Each request is Ed25519-signed via
+ * `X-Signature-Ed25519` + `X-Signature-Timestamp`.
+ *
+ * Discord requires the bot to respond *to the request itself* — the
+ * gateway POSTs the interaction-response body back. For backward
+ * compatibility with the channel adapter contract, `sendReply` instead
+ * uses Discord's "follow-up message" API (`POST /webhooks/{appId}/{token}`)
+ * which works at any time after the initial deferred response.
+ *
+ * Thread session keying uses Discord's native `thread_id` when present
+ * (forum / public thread / archived thread); otherwise the channel id.
+ */
+import { CrewhausError } from "@crewhaus/errors";
+import { verifyDiscordSignature } from "./verify.js";
+export { generateEd25519Keypair, signDiscordBody, verifyDiscordSignature, } from "./verify.js";
+export class DiscordAdapterError extends CrewhausError {
+    name = "DiscordAdapterError";
+    constructor(message, cause) {
+        super("channel", message, cause);
+    }
+}
+const DEFAULT_API_BASE_URL = "https://discord.com/api/v10";
+const PONG_RESPONSE_BODY = JSON.stringify({ type: 1 });
+export function createDiscordAdapter(config, opts = {}) {
+    const apiBaseUrl = opts.apiBaseUrl ?? process.env["DISCORD_API_BASE_URL"] ?? DEFAULT_API_BASE_URL;
+    const doFetch = opts.fetch ?? fetch;
+    return {
+        id: "discord",
+        verify(req) {
+            return verifyDiscordSignature({
+                headers: req.headers,
+                body: req.body,
+                publicKeyHex: config.publicKeyHex,
+            }, 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;
+            // PING → PONG handshake (Discord's URL-verification analogue).
+            if (p.type === 1) {
+                return { kind: "challenge", challenge: PONG_RESPONSE_BODY };
+            }
+            // We handle types 2 (slash command), 3 (component click), 5 (modal submit).
+            if (p.type !== 2 && p.type !== 3 && p.type !== 5) {
+                return { kind: "skip" };
+            }
+            const interactionId = p.id;
+            const channelId = p.channel_id;
+            const userId = p.member?.user?.id ?? p.user?.id;
+            if (!interactionId || !channelId || !userId)
+                return { kind: "skip" };
+            const workspaceId = p.guild_id ?? "dm";
+            // Threads: in Discord a "thread" is a Channel with `parent_id` set
+            // and type 11 (public thread) / 12 (private thread) / 10 (news
+            // thread). The interaction.channel object includes `parent_id` when
+            // the interaction is in a thread.
+            const isThread = typeof p.channel?.parent_id === "string" && p.channel.parent_id.length > 0;
+            const threadTs = isThread ? channelId : undefined;
+            const text = renderInteractionText(p);
+            const event = {
+                idempotencyKey: interactionId,
+                workspaceId,
+                channelId,
+                userId,
+                ...(threadTs !== undefined ? { threadTs } : {}),
+                ts: interactionId,
+                text,
+                subtype: "message",
+            };
+            return { kind: "event", event };
+        },
+        async sendReply(args) {
+            // Use Discord's interaction follow-up endpoint:
+            //   POST /webhooks/{application.id}/{interaction.token}
+            // The interaction.token isn't part of `InboundEvent`; in practice the
+            // gateway should call `interaction.respond({type:5, data: {...}})`
+            // synchronously to defer, then we follow up via this REST call. For
+            // the v0 channel-bot daemon we use the application's webhook channel
+            // POST as a fallback so the message reaches the channel even without
+            // the interaction token (slightly different rendering — no
+            // ephemeral, no per-user replies).
+            const url = `${apiBaseUrl}/channels/${args.event.channelId}/messages`;
+            const res = await doFetch(url, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bot ${config.botToken}`,
+                },
+                body: JSON.stringify({ content: args.text }),
+            });
+            if (!res.ok) {
+                throw new DiscordAdapterError(`channels/${args.event.channelId}/messages failed: ${res.status} ${res.statusText}`);
+            }
+        },
+        // Note: no `react()` hook. Discord's inbound is an *interaction* (slash
+        // command / component / modal), not a channel message, and `event.ts` is
+        // the interaction id — there is no user message to attach a reaction to.
+        // The session-router skips the (undefined) react hook silently, so status
+        // acks simply don't appear on Discord. (Slack/Telegram/WhatsApp implement
+        // react(); iMessage cannot.)
+        async setTyping(args) {
+            const url = `${apiBaseUrl}/channels/${args.event.channelId}/typing`;
+            // Best-effort — do not surface failures. A failed typing indicator must
+            // never reject and break the caller's reply flow, so we swallow both
+            // network rejections (DNS/abort/connection) and non-2xx responses.
+            try {
+                await doFetch(url, {
+                    method: "POST",
+                    headers: {
+                        Authorization: `Bot ${config.botToken}`,
+                    },
+                });
+            }
+            catch {
+                // ignore — typing indicator is non-essential.
+            }
+        },
+    };
+}
+/** Reduce an interaction payload to a single text body for the agent. */
+function renderInteractionText(p) {
+    if (p.type === 2) {
+        // Slash command: render as `/<name> <option1=value1> <option2=value2>`
+        const cmd = p.data?.name ?? "?";
+        const opts = (p.data?.options ?? [])
+            .map((o) => `${o.name}=${stringifyOption(o.value)}`)
+            .join(" ");
+        return opts ? `/${cmd} ${opts}` : `/${cmd}`;
+    }
+    if (p.type === 3) {
+        // Component click: `[component:<custom_id>]`
+        return `[component:${p.data?.custom_id ?? ""}]`;
+    }
+    if (p.type === 5) {
+        // Modal submit: render as `<custom_id>: field1=value1 field2=value2`
+        const id = p.data?.custom_id ?? "";
+        const fields = (p.data?.components ?? [])
+            .flatMap((row) => row.components ?? [])
+            .map((c) => `${c.custom_id ?? "?"}=${c.value ?? ""}`)
+            .join(" ");
+        return `${id}: ${fields}`;
+    }
+    return "";
+}
+function stringifyOption(v) {
+    if (v === null || v === undefined)
+        return "";
+    if (typeof v === "string")
+        return v;
+    return JSON.stringify(v);
+}

package/dist/verify.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Discord interaction signature verification per
+ * https://discord.com/developers/docs/interactions/receiving-and-responding#security-and-authorization.
+ *
+ * Discord signs interaction webhooks with Ed25519. Each request carries
+ * `X-Signature-Ed25519` (hex) and `X-Signature-Timestamp` (seconds). The
+ * signed payload is `<timestamp><body>`. The bot's `publicKey` (hex,
+ * 64 chars) is the verification key.
+ *
+ * We use Node's built-in `crypto.verify` with `null` algorithm and an
+ * Ed25519 KeyObject built from the raw 32-byte public key — no external
+ * SDK needed.
+ */
+export type DiscordVerifyArgs = {
+    readonly headers: Headers;
+    readonly body: string;
+    readonly publicKeyHex: string;
+};
+export type DiscordVerifyOptions = {
+    readonly now?: () => number;
+    readonly toleranceMs?: number;
+};
+export declare function verifyDiscordSignature(args: DiscordVerifyArgs, opts?: DiscordVerifyOptions): boolean;
+/**
+ * Sign a body with an Ed25519 private key — used by smoke tests and the
+ * in-repo integration test to construct fixtures the daemon will accept.
+ * Production code should NEVER call this — Discord signs requests, not us.
+ */
+export declare function signDiscordBody(args: {
+    body: string;
+    timestamp: number | string;
+    privateKeyPem: string;
+}): string;
+/**
+ * Generate a fresh Ed25519 keypair (PEM-encoded). Used by the test
+ * harness so we can sign + verify our own fixtures end-to-end.
+ */
+export declare function generateEd25519Keypair(): {
+    publicKeyHex: string;
+    privateKeyPem: string;
+};

package/dist/verify.js

@@ -0,0 +1,87 @@
+import { createPrivateKey, createPublicKey, sign as cryptoSign, generateKeyPairSync, verify, } from "node:crypto";
+// Discord recommends rejecting interactions whose timestamp is too far from
+// now; 5 minutes matches the Slack adapter's replay-window cap.
+const DEFAULT_TOLERANCE_MS = 5 * 60 * 1000;
+export function verifyDiscordSignature(args, opts = {}) {
+    const now = opts.now ?? (() => Date.now());
+    const tolerance = opts.toleranceMs ?? DEFAULT_TOLERANCE_MS;
+    const sigHex = args.headers.get("x-signature-ed25519");
+    const timestamp = args.headers.get("x-signature-timestamp");
+    if (!sigHex || !timestamp)
+        return false;
+    if (!/^[0-9a-f]{128}$/i.test(sigHex))
+        return false;
+    if (!/^\d+$/.test(timestamp))
+        return false;
+    // Replay-window: the timestamp is folded into the signed payload, so a
+    // captured (timestamp, body, signature) triple verifies indefinitely
+    // without this freshness bound. Reject stale/future timestamps (seconds
+    // since epoch), mirroring the Slack adapter.
+    const tsNum = Number.parseInt(timestamp, 10);
+    if (!Number.isFinite(tsNum))
+        return false;
+    if (Math.abs(now() - tsNum * 1000) > tolerance)
+        return false;
+    // `sigHex` is regex-validated above to be exactly 128 hex chars, so
+    // `Buffer.from(_, "hex")` always yields exactly 64 bytes and never throws
+    // (`Buffer.from` silently drops invalid hex rather than throwing). The
+    // length re-check below is a cheap, defensive belt for that invariant.
+    const signature = Buffer.from(sigHex, "hex");
+    if (signature.length !== 64)
+        return false;
+    let publicKey;
+    try {
+        publicKey = ed25519PublicKeyFromHex(args.publicKeyHex);
+    }
+    catch {
+        return false;
+    }
+    const message = Buffer.from(`${timestamp}${args.body}`, "utf8");
+    try {
+        return verify(null, message, publicKey, signature);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Construct an Ed25519 public KeyObject from a 32-byte hex string. Discord's
+ * docs publish the bot key as a 64-char hex string. Node's `createPublicKey`
+ * accepts a SubjectPublicKeyInfo DER blob — we wrap the raw key with the
+ * fixed Ed25519 OID prefix `302a300506032b6570032100`.
+ */
+function ed25519PublicKeyFromHex(hex) {
+    if (!/^[0-9a-f]{64}$/i.test(hex)) {
+        throw new Error(`expected 32-byte (64-char hex) ed25519 public key, got ${hex.length} chars`);
+    }
+    const der = Buffer.concat([
+        Buffer.from("302a300506032b6570032100", "hex"),
+        Buffer.from(hex, "hex"),
+    ]);
+    return createPublicKey({ key: der, format: "der", type: "spki" });
+}
+/**
+ * Sign a body with an Ed25519 private key — used by smoke tests and the
+ * in-repo integration test to construct fixtures the daemon will accept.
+ * Production code should NEVER call this — Discord signs requests, not us.
+ */
+export function signDiscordBody(args) {
+    const message = Buffer.from(`${args.timestamp}${args.body}`, "utf8");
+    const sk = createPrivateKey({ key: args.privateKeyPem });
+    const sig = cryptoSign(null, message, sk);
+    return sig.toString("hex");
+}
+/**
+ * Generate a fresh Ed25519 keypair (PEM-encoded). Used by the test
+ * harness so we can sign + verify our own fixtures end-to-end.
+ */
+export function generateEd25519Keypair() {
+    const { publicKey, privateKey } = generateKeyPairSync("ed25519");
+    // Extract raw 32-byte public key from the DER-encoded SPKI:
+    // SPKI = 30 2a 30 05 06 03 2b 65 70 03 21 00 <32-byte-key>
+    const spkiDer = publicKey.export({ format: "der", type: "spki" });
+    const rawKey = spkiDer.subarray(spkiDer.length - 32);
+    const publicKeyHex = Buffer.from(rawKey).toString("hex");
+    const privateKeyPem = privateKey.export({ format: "pem", type: "pkcs8" }).toString();
+    return { publicKeyHex, privateKeyPem };
+}

package/package.json

@@ -1,18 +1,21 @@
 {
   "name": "@crewhaus/channel-adapter-discord",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "type": "module",
   "description": "Discord channel adapter: Ed25519 signature verification + slash-command/button/modal interaction parsing + interaction-response API (Section 33)",
-  "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.3"
+    "@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/component_button.json

@@ -1,13 +0,0 @@
-{
-  "id": "100000000000000006",
-  "application_id": "200000000000000001",
-  "type": 3,
-  "token": "tok-btn",
-  "channel_id": "300000000000000001",
-  "guild_id": "400000000000000001",
-  "member": { "user": { "id": "500000000000000001", "username": "alice" } },
-  "data": {
-    "custom_id": "approve:doc-123",
-    "component_type": 2
-  }
-}

package/src/fixtures/missing_user.json

@@ -1,9 +0,0 @@
-{
-  "id": "100000000000000009",
-  "application_id": "200000000000000001",
-  "type": 2,
-  "token": "tok-no-user",
-  "channel_id": "300000000000000001",
-  "guild_id": "400000000000000001",
-  "data": { "name": "ping" }
-}

package/src/fixtures/modal_submit.json

@@ -1,22 +0,0 @@
-{
-  "id": "100000000000000007",
-  "application_id": "200000000000000001",
-  "type": 5,
-  "token": "tok-modal",
-  "channel_id": "300000000000000001",
-  "guild_id": "400000000000000001",
-  "member": { "user": { "id": "500000000000000001", "username": "alice" } },
-  "data": {
-    "custom_id": "feedback-form",
-    "components": [
-      {
-        "type": 1,
-        "components": [{ "type": 4, "custom_id": "rating", "value": "5" }]
-      },
-      {
-        "type": 1,
-        "components": [{ "type": 4, "custom_id": "comment", "value": "loved it" }]
-      }
-    ]
-  }
-}

package/src/fixtures/ping.json

@@ -1,6 +0,0 @@
-{
-  "id": "100000000000000001",
-  "application_id": "200000000000000001",
-  "type": 1,
-  "token": "ping-token"
-}

package/src/fixtures/slash_command_basic.json

@@ -1,13 +0,0 @@
-{
-  "id": "100000000000000002",
-  "application_id": "200000000000000001",
-  "type": 2,
-  "token": "tok-basic",
-  "channel_id": "300000000000000001",
-  "guild_id": "400000000000000001",
-  "member": { "user": { "id": "500000000000000001", "username": "alice" } },
-  "data": {
-    "name": "ping",
-    "options": []
-  }
-}

package/src/fixtures/slash_command_dm.json

@@ -1,12 +0,0 @@
-{
-  "id": "100000000000000005",
-  "application_id": "200000000000000001",
-  "type": 2,
-  "token": "tok-dm",
-  "channel_id": "300000000000000077",
-  "user": { "id": "500000000000000007", "username": "bob" },
-  "data": {
-    "name": "help",
-    "options": []
-  }
-}

package/src/fixtures/slash_command_thread.json

@@ -1,14 +0,0 @@
-{
-  "id": "100000000000000004",
-  "application_id": "200000000000000001",
-  "type": 2,
-  "token": "tok-thread",
-  "channel_id": "300000000000000099",
-  "guild_id": "400000000000000001",
-  "channel": { "id": "300000000000000099", "parent_id": "300000000000000001" },
-  "member": { "user": { "id": "500000000000000001", "username": "alice" } },
-  "data": {
-    "name": "explain",
-    "options": []
-  }
-}

package/src/fixtures/slash_command_with_options.json

@@ -1,16 +0,0 @@
-{
-  "id": "100000000000000003",
-  "application_id": "200000000000000001",
-  "type": 2,
-  "token": "tok-opts",
-  "channel_id": "300000000000000001",
-  "guild_id": "400000000000000001",
-  "member": { "user": { "id": "500000000000000001", "username": "alice" } },
-  "data": {
-    "name": "summarize",
-    "options": [
-      { "name": "url", "type": 3, "value": "https://example.com" },
-      { "name": "depth", "type": 4, "value": 3 }
-    ]
-  }
-}

package/src/fixtures/unknown_type.json

@@ -1,7 +0,0 @@
-{
-  "id": "100000000000000008",
-  "application_id": "200000000000000001",
-  "type": 4,
-  "token": "tok-autocomplete",
-  "channel_id": "300000000000000001"
-}