@crewhaus/channel-adapter-discord 0.1.0

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@crewhaus/channel-adapter-discord",
+  "version": "0.1.0",
+  "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",
+  "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-discord"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/channel-adapter-discord#readme",
+  "bugs": {
+    "url": "https://github.com/crewhaus/factory/issues"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ]
+}

package/src/fixtures/component_button.json

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

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

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

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

package/src/fixtures/slash_command_basic.json

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

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

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

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

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

package/src/index.test.ts

@@ -0,0 +1,299 @@
+import { beforeAll, describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import {
+  type ChannelAdapter,
+  DiscordAdapterError,
+  type InboundEvent,
+  type ParsedInbound,
+  type RawRequest,
+  createDiscordAdapter,
+  generateEd25519Keypair,
+  signDiscordBody,
+  verifyDiscordSignature,
+} 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_DIR = join(import.meta.dir.replace(/([/\\])dist$/, "$1src"), "fixtures");
+const fixture = (name: string) => readFileSync(join(FIXTURES_DIR, `${name}.json`), "utf8");
+
+let publicKeyHex: string;
+let privateKeyPem: string;
+let otherPublicKeyHex: string;
+
+beforeAll(() => {
+  const k = generateEd25519Keypair();
+  publicKeyHex = k.publicKeyHex;
+  privateKeyPem = k.privateKeyPem;
+  otherPublicKeyHex = generateEd25519Keypair().publicKeyHex;
+});
+
+function signedHeaders(body: string, ts: string | number = "1700000000"): Headers {
+  const sig = signDiscordBody({ body, timestamp: ts, privateKeyPem });
+  const h = new Headers();
+  h.set("X-Signature-Ed25519", sig);
+  h.set("X-Signature-Timestamp", String(ts));
+  return h;
+}
+
+function adapter(
+  overrides: Partial<{ publicKeyHex: string; fetch: typeof fetch }> = {},
+): ChannelAdapter {
+  return createDiscordAdapter(
+    {
+      applicationId: "200000000000000001",
+      botToken: "Bot.token",
+      publicKeyHex: overrides.publicKeyHex ?? publicKeyHex,
+    },
+    {
+      apiBaseUrl: "https://test.discord.local",
+      ...(overrides.fetch ? { fetch: overrides.fetch } : {}),
+    },
+  );
+}
+
+describe("verifyDiscordSignature (T8)", () => {
+  test("matches a valid signature", () => {
+    const body = fixture("ping");
+    const r = verifyDiscordSignature({
+      headers: signedHeaders(body),
+      body,
+      publicKeyHex,
+    });
+    expect(r).toBe(true);
+  });
+
+  test("rejects a tampered body", () => {
+    const body = fixture("ping");
+    const headers = signedHeaders(body);
+    expect(
+      verifyDiscordSignature({
+        headers,
+        body: `${body}--tampered`,
+        publicKeyHex,
+      }),
+    ).toBe(false);
+  });
+
+  test("rejects wrong public key", () => {
+    const body = fixture("ping");
+    expect(
+      verifyDiscordSignature({
+        headers: signedHeaders(body),
+        body,
+        publicKeyHex: otherPublicKeyHex,
+      }),
+    ).toBe(false);
+  });
+
+  test("rejects missing X-Signature-Ed25519 header", () => {
+    const body = fixture("ping");
+    const headers = signedHeaders(body);
+    headers.delete("X-Signature-Ed25519");
+    expect(verifyDiscordSignature({ headers, body, publicKeyHex })).toBe(false);
+  });
+
+  test("rejects missing X-Signature-Timestamp header", () => {
+    const body = fixture("ping");
+    const headers = signedHeaders(body);
+    headers.delete("X-Signature-Timestamp");
+    expect(verifyDiscordSignature({ headers, body, publicKeyHex })).toBe(false);
+  });
+
+  test("rejects malformed sig hex (wrong length)", () => {
+    const body = fixture("ping");
+    const headers = new Headers({
+      "X-Signature-Ed25519": "deadbeef",
+      "X-Signature-Timestamp": "1700000000",
+    });
+    expect(verifyDiscordSignature({ headers, body, publicKeyHex })).toBe(false);
+  });
+
+  test("rejects non-numeric timestamp", () => {
+    const body = fixture("ping");
+    const headers = signedHeaders(body, "abc");
+    expect(verifyDiscordSignature({ headers, body, publicKeyHex })).toBe(false);
+  });
+
+  test("rejects malformed publicKeyHex", () => {
+    const body = fixture("ping");
+    expect(
+      verifyDiscordSignature({
+        headers: signedHeaders(body),
+        body,
+        publicKeyHex: "not-hex",
+      }),
+    ).toBe(false);
+  });
+});
+
+describe("parseInbound — fixtures (T2)", () => {
+  test("ping → challenge with PONG body", () => {
+    const a = adapter();
+    const body = fixture("ping");
+    const r = a.parseInbound({ headers: signedHeaders(body), body });
+    expect(r.kind).toBe("challenge");
+    if (r.kind === "challenge") {
+      expect(JSON.parse(r.challenge)).toEqual({ type: 1 });
+    }
+  });
+
+  test("slash_command_basic → event with text /<name>", () => {
+    const a = adapter();
+    const body = fixture("slash_command_basic");
+    const r = a.parseInbound({ headers: signedHeaders(body), body }) as Extract<
+      ParsedInbound,
+      { kind: "event" }
+    >;
+    expect(r.kind).toBe("event");
+    expect(r.event.text).toBe("/ping");
+    expect(r.event.channelId).toBe("300000000000000001");
+    expect(r.event.userId).toBe("500000000000000001");
+    expect(r.event.workspaceId).toBe("400000000000000001");
+    expect(r.event.threadTs).toBeUndefined();
+  });
+
+  test("slash_command_with_options → text encodes name=value pairs", () => {
+    const a = adapter();
+    const body = fixture("slash_command_with_options");
+    const r = a.parseInbound({ headers: signedHeaders(body), body }) as Extract<
+      ParsedInbound,
+      { kind: "event" }
+    >;
+    expect(r.event.text).toBe("/summarize url=https://example.com depth=3");
+  });
+
+  test("slash_command_thread → channelId is thread id, threadTs set", () => {
+    const a = adapter();
+    const body = fixture("slash_command_thread");
+    const r = a.parseInbound({ headers: signedHeaders(body), body }) as Extract<
+      ParsedInbound,
+      { kind: "event" }
+    >;
+    expect(r.event.channelId).toBe("300000000000000099");
+    expect(r.event.threadTs).toBe("300000000000000099");
+  });
+
+  test('slash_command_dm → workspaceId is "dm", user.id used', () => {
+    const a = adapter();
+    const body = fixture("slash_command_dm");
+    const r = a.parseInbound({ headers: signedHeaders(body), body }) as Extract<
+      ParsedInbound,
+      { kind: "event" }
+    >;
+    expect(r.event.workspaceId).toBe("dm");
+    expect(r.event.userId).toBe("500000000000000007");
+  });
+
+  test("component_button → text [component:<custom_id>]", () => {
+    const a = adapter();
+    const body = fixture("component_button");
+    const r = a.parseInbound({ headers: signedHeaders(body), body }) as Extract<
+      ParsedInbound,
+      { kind: "event" }
+    >;
+    expect(r.event.text).toBe("[component:approve:doc-123]");
+  });
+
+  test("modal_submit → text encodes form fields", () => {
+    const a = adapter();
+    const body = fixture("modal_submit");
+    const r = a.parseInbound({ headers: signedHeaders(body), body }) as Extract<
+      ParsedInbound,
+      { kind: "event" }
+    >;
+    expect(r.event.text).toBe("feedback-form: rating=5 comment=loved it");
+  });
+
+  test("unknown_type → skip", () => {
+    const a = adapter();
+    const body = fixture("unknown_type");
+    const r = a.parseInbound({ headers: signedHeaders(body), body });
+    expect(r.kind).toBe("skip");
+  });
+
+  test("missing_user → skip", () => {
+    const a = adapter();
+    const body = fixture("missing_user");
+    const r = a.parseInbound({ headers: signedHeaders(body), body });
+    expect(r.kind).toBe("skip");
+  });
+
+  test("malformed JSON → skip", () => {
+    const a = adapter();
+    const r = a.parseInbound({ headers: new Headers(), body: "not json{" });
+    expect(r.kind).toBe("skip");
+  });
+
+  test("idempotencyKey == interaction id", () => {
+    const a = adapter();
+    const body = fixture("slash_command_basic");
+    const r = a.parseInbound({ headers: signedHeaders(body), body }) as Extract<
+      ParsedInbound,
+      { kind: "event" }
+    >;
+    expect(r.event.idempotencyKey).toBe("100000000000000002");
+  });
+});
+
+describe("sendReply / setTyping (T3)", () => {
+  function captureFetch() {
+    const calls: Array<{ url: string; init: RequestInit }> = [];
+    const f = (async (input: string | Request | URL, init?: RequestInit) => {
+      calls.push({ url: String(input), init: init ?? {} });
+      return new Response("", { status: 204 });
+    }) as unknown as typeof fetch;
+    return { calls, fetch: f };
+  }
+
+  const event: InboundEvent = {
+    idempotencyKey: "100000000000000002",
+    workspaceId: "400000000000000001",
+    channelId: "300000000000000001",
+    userId: "500000000000000001",
+    ts: "100000000000000002",
+    text: "/ping",
+    subtype: "message",
+  };
+
+  test("sendReply POSTs /channels/{channelId}/messages with content", async () => {
+    const { calls, fetch: f } = captureFetch();
+    const a = adapter({ fetch: f });
+    await a.sendReply({ event, text: "pong" });
+    expect(calls.length).toBe(1);
+    expect(calls[0]?.url).toBe("https://test.discord.local/channels/300000000000000001/messages");
+    const body = JSON.parse(String(calls[0]?.init.body));
+    expect(body.content).toBe("pong");
+    const auth = (calls[0]?.init.headers as Record<string, string> | undefined)?.["Authorization"];
+    expect(auth).toBe("Bot Bot.token");
+  });
+
+  test("sendReply throws DiscordAdapterError on HTTP error", async () => {
+    const f = (async () =>
+      new Response("server fail", {
+        status: 500,
+        statusText: "Internal",
+      })) as unknown as typeof fetch;
+    const a = adapter({ fetch: f });
+    await expect(a.sendReply({ event, text: "x" })).rejects.toThrow(DiscordAdapterError);
+  });
+
+  test("setTyping POSTs /channels/{channelId}/typing", async () => {
+    const { calls, fetch: f } = captureFetch();
+    const a = adapter({ fetch: f });
+    await a.setTyping({ event });
+    expect(calls.length).toBe(1);
+    expect(calls[0]?.url).toBe("https://test.discord.local/channels/300000000000000001/typing");
+  });
+});
+
+describe("createDiscordAdapter.verify()", () => {
+  test("forwards to verifyDiscordSignature", () => {
+    const a = adapter();
+    const body = fixture("ping");
+    expect(a.verify({ headers: signedHeaders(body), body })).toBe(true);
+    expect(a.verify({ headers: new Headers(), body })).toBe(false);
+  });
+});

package/src/index.ts

@@ -0,0 +1,261 @@
+/**
+ * @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 {
+  override readonly name = "DiscordAdapterError";
+  constructor(message: string, cause?: unknown) {
+    super("channel", message, cause);
+  }
+}
+
+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;
+};
+
+const DEFAULT_API_BASE_URL = "https://discord.com/api/v10";
+const PONG_RESPONSE_BODY = JSON.stringify({ type: 1 });
+
+export function createDiscordAdapter(
+  config: DiscordAdapterConfig,
+  opts: DiscordAdapterOptions = {},
+): ChannelAdapter {
+  const apiBaseUrl = opts.apiBaseUrl ?? process.env["DISCORD_API_BASE_URL"] ?? DEFAULT_API_BASE_URL;
+  const doFetch = opts.fetch ?? fetch;
+
+  return {
+    id: "discord",
+
+    verify(req: RawRequest): boolean {
+      return verifyDiscordSignature({
+        headers: req.headers,
+        body: req.body,
+        publicKeyHex: config.publicKeyHex,
+      });
+    },
+
+    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 DiscordInteraction;
+
+      // 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: InboundEvent = {
+        idempotencyKey: interactionId,
+        workspaceId,
+        channelId,
+        userId,
+        ...(threadTs !== undefined ? { threadTs } : {}),
+        ts: interactionId,
+        text,
+        subtype: "message",
+      };
+      return { kind: "event", event };
+    },
+
+    async sendReply(args: { event: InboundEvent; text: string }): Promise<void> {
+      // 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}`,
+        );
+      }
+    },
+
+    async setTyping(args: { event: InboundEvent }): Promise<void> {
+      const url = `${apiBaseUrl}/channels/${args.event.channelId}/typing`;
+      await doFetch(url, {
+        method: "POST",
+        headers: {
+          Authorization: `Bot ${config.botToken}`,
+        },
+      });
+      // Best-effort — do not surface failures.
+    },
+  };
+}
+
+/** Reduce an interaction payload to a single text body for the agent. */
+function renderInteractionText(p: DiscordInteraction): string {
+  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: unknown): string {
+  if (v === null || v === undefined) return "";
+  if (typeof v === "string") return v;
+  return JSON.stringify(v);
+}
+
+// ─── Minimal Discord interaction shape (no SDK) ──────────────────────────────
+
+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/src/verify.ts

@@ -0,0 +1,107 @@
+import {
+  createPrivateKey,
+  createPublicKey,
+  sign as cryptoSign,
+  generateKeyPairSync,
+  verify,
+} from "node:crypto";
+
+/**
+ * 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 function verifyDiscordSignature(args: DiscordVerifyArgs): boolean {
+  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;
+
+  let signature: Buffer;
+  try {
+    signature = Buffer.from(sigHex, "hex");
+  } catch {
+    return false;
+  }
+  if (signature.length !== 64) return false;
+
+  let publicKey: ReturnType<typeof ed25519PublicKeyFromHex>;
+  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: string) {
+  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: {
+  body: string;
+  timestamp: number | string;
+  privateKeyPem: string;
+}): string {
+  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(): {
+  publicKeyHex: string;
+  privateKeyPem: string;
+} {
+  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 };
+}