@open-everywhere/provider-discord 0.1.0

package/agent/channels/discord-events.ts

@@ -0,0 +1,175 @@
+// Discord WEBHOOK EVENTS — the app-level install/uninstall audit trail (OPE-118 Discord §9).
+//
+// Distinct from BOTH of Discord's other webhook-shaped things, which is the whole reason this file
+// carries a header:
+//   • NOT an "incoming webhook" (§6) — that's a channel-scoped POST-only credential;
+//   • NOT the Interactions Endpoint (§5, discord-front.ts) — that's slash commands / button clicks.
+// Webhook Events are configured on a SEPARATE "Webhooks" page of the app in the developer portal
+// (its own URL), delivered app-level, and — critically — they do NOT carry ordinary chat events.
+// Channel messages remain Gateway-only (§8, deploy/discord-relay); the ONLY thing OE wants here is
+// `APPLICATION_AUTHORIZED` / `APPLICATION_DEAUTHORIZED`: the real-time signal that a guild admin
+// installed or removed the app, which OE previously had no way to see short of noticing silence.
+//
+// OBSERVABILITY ONLY. This route gates nothing, drops nothing, and wakes nothing — it writes audit
+// rows. A failure to audit is swallowed (the appendAudit layer is best-effort by contract) and the
+// endpoint still acks, because a non-2xx makes Discord retry and eventually SUSPEND delivery.
+//
+// Payload shape verified against docs.discord.com/developers/events/webhook-events (2026-07):
+//   { version: 1, application_id, type, event: { type, timestamp, data } }
+//   type 0 = PING (endpoint verification), type 1 = Event.
+//   APPLICATION_AUTHORIZED   data: { integration_type, user, scopes, guild? }
+//     — integration_type 0 = guild install (guild present), 1 = user install (no guild).
+//   APPLICATION_DEAUTHORIZED data: { user }   (no guild, no scopes — Discord sends neither)
+// Discord requires a 204 with an EMPTY body within 3s for both the PING and every event, and a 401
+// when signature validation fails; repeated failures get the endpoint unregistered.
+//
+// Signature: the SAME Ed25519 app public key the Interactions Endpoint uses, so this reuses
+// `verifyDiscordInteraction` (discord-front.ts) verbatim rather than standing up a second
+// verification path — one key, one verifier.
+
+import { POST, type Channel, type RouteHandlerArgs } from "eve/channels";
+import { verifyDiscordInteraction } from "./discord-front.js";
+import { appendAudit, deploymentOrg } from "@open-everywhere/core/agent/adapter-api.js";
+
+/** The public URL to paste into the app's developer-portal **Webhooks** page (NOT the
+ *  Interactions Endpoint URL, which stays {@link PUBLIC_DISCORD_ROUTE}). */
+export const PUBLIC_DISCORD_EVENTS_ROUTE = "/eve/v1/discord/events";
+
+/** Discord's outer webhook `type`. */
+const WEBHOOK_TYPE_PING = 0;
+const WEBHOOK_TYPE_EVENT = 1;
+
+function elog(msg: string): void {
+  console.log(`[open-everywhere:discord-events] ${msg}`);
+}
+
+/** The decision one verified Webhook Events body resolves to. `ack` covers everything we
+ *  deliberately don't act on (a PING, an entitlement/social-SDK event, an unparseable body) —
+ *  all of which still get Discord's required 204. */
+export type DiscordEventDecision =
+  | { readonly kind: "ack"; readonly reason: string }
+  | { readonly kind: "audit"; readonly action: string; readonly workspace: string; readonly principalId?: string; readonly detail: Record<string, unknown> };
+
+function str(v: unknown): string | undefined {
+  return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+
+function obj(v: unknown): Record<string, unknown> | undefined {
+  return typeof v === "object" && v !== null && !Array.isArray(v) ? (v as Record<string, unknown>) : undefined;
+}
+
+/**
+ * Classify one raw Webhook Events body. PURE — no I/O, so every branch is unit-tested.
+ *
+ * The audit partition mirrors what the rest of the Discord surface uses: the GUILD is the
+ * workspace (the org boundary — `bindDiscord` maps guild→workspace), and the authorizing user is
+ * the principal. A USER install (integration_type 1) has no guild at all, so it partitions under
+ * the sentinel workspace `user-install` rather than being forced into a guild it doesn't have —
+ * a fabricated workspace id would be worse than an honest one.
+ */
+export function classifyDiscordEvent(rawBody: string): DiscordEventDecision {
+  let json: unknown;
+  try {
+    json = JSON.parse(rawBody);
+  } catch {
+    return { kind: "ack", reason: "unparseable body" };
+  }
+  const p = obj(json);
+  if (!p) return { kind: "ack", reason: "non-object body" };
+  if (p["type"] === WEBHOOK_TYPE_PING) return { kind: "ack", reason: "PING — endpoint verification" };
+  if (p["type"] !== WEBHOOK_TYPE_EVENT) return { kind: "ack", reason: `webhook type ${String(p["type"])} — not an event` };
+
+  const event = obj(p["event"]);
+  const eventType = str(event?.["type"]);
+  if (eventType !== "APPLICATION_AUTHORIZED" && eventType !== "APPLICATION_DEAUTHORIZED") {
+    // Entitlements, Social-SDK lobby/DM events, and anything Discord adds later: acked, unaudited.
+    return { kind: "ack", reason: `event ${eventType ?? "?"} — not an install/uninstall` };
+  }
+
+  const data = obj(event?.["data"]);
+  const guild = obj(data?.["guild"]);
+  const guildId = str(guild?.["id"]);
+  const userId = str(obj(data?.["user"])?.["id"]);
+  // integration_type is only sent on AUTHORIZED; 0 = guild install, 1 = user install.
+  const integrationType = typeof data?.["integration_type"] === "number" ? (data["integration_type"] as number) : undefined;
+  const scopes = Array.isArray(data?.["scopes"]) ? (data["scopes"] as unknown[]).filter((s): s is string => typeof s === "string") : undefined;
+
+  return {
+    kind: "audit",
+    action: eventType === "APPLICATION_AUTHORIZED" ? "surface.app_installed" : "surface.app_uninstalled",
+    // A DEAUTHORIZED payload carries no guild (Discord sends only `user`), so an uninstall of a
+    // guild install partitions as unknown — honest, and the paired install row names the guild.
+    workspace: guildId ?? (integrationType === 1 ? "user-install" : "unknown"),
+    ...(userId ? { principalId: userId } : {}),
+    detail: {
+      event: eventType,
+      ...(integrationType !== undefined ? { integrationType } : {}),
+      ...(guildId ? { guildId } : {}),
+      // Scope names only — the grant's shape, not any member data.
+      ...(scopes && scopes.length > 0 ? { scopes } : {}),
+      ...(str(event?.["timestamp"]) ? { eventTimestamp: str(event?.["timestamp"]) } : {}),
+    },
+  };
+}
+
+/** Injectable seams so the route is testable without live crypto env or the real store. */
+export interface DiscordEventsOptions {
+  /** The app public key; defaults to DISCORD_PUBLIC_KEY (the same env the interactions path reads). */
+  readonly publicKey?: string;
+  readonly now?: () => number;
+  /** Audit writer (defaults to the real appendAudit under the deployment org). */
+  readonly audit?: (row: { action: string; workspace: string; principalId?: string; detail: Record<string, unknown> }) => Promise<void>;
+}
+
+/** Discord requires an EMPTY 204 body for both the PING and every event, within 3 seconds. */
+const ACK = () => new Response(null, { status: 204 });
+
+/**
+ * Build the Webhook Events route handler: verify (fail-closed 401), classify, audit, ack.
+ *
+ * The audit write is deliberately AWAITED rather than backgrounded — a `surface.app_*` row is one
+ * cheap insert and Discord's budget is 3 seconds, so we'd rather the row land than shave a
+ * millisecond. It is also wrapped: an audit failure must never turn into a non-2xx, because
+ * Discord retries a failure and then suspends the endpoint — losing the very observability this
+ * route exists to provide.
+ */
+export function buildDiscordEventsHandler(opts: DiscordEventsOptions = {}): (req: Request, args: RouteHandlerArgs) => Promise<Response> {
+  const now = opts.now ?? (() => Date.now());
+  const publicKey = () => opts.publicKey ?? process.env.DISCORD_PUBLIC_KEY;
+  const audit =
+    opts.audit ??
+    (async (row) => {
+      await appendAudit({ org: deploymentOrg(), platform: "discord", workspace: row.workspace, ...(row.principalId ? { principalId: row.principalId } : {}), action: row.action, detail: row.detail });
+    });
+
+  return async (req: Request): Promise<Response> => {
+    const rawBody = await req.text();
+    if (!verifyDiscordInteraction(rawBody, req.headers, publicKey(), now())) {
+      return new Response("unauthorized", { status: 401 });
+    }
+    const decision = classifyDiscordEvent(rawBody);
+    if (decision.kind === "ack") {
+      elog(`acked: ${decision.reason}`);
+      return ACK();
+    }
+    try {
+      await audit({ action: decision.action, workspace: decision.workspace, ...(decision.principalId ? { principalId: decision.principalId } : {}), detail: decision.detail });
+      elog(`${decision.detail["event"]} on ${decision.workspace} audited as ${decision.action}`);
+    } catch (err) {
+      // Observability-only: never let a failed row become a delivery failure (Discord would retry,
+      // then suspend the endpoint).
+      elog(`audit write failed (acked anyway): ${String(err)}`);
+    }
+    return ACK();
+  };
+}
+
+/**
+ * Mount the Webhook Events route onto the Discord channel. Additive: it only PREPENDS a route to
+ * the same channel object (one channel name → one session namespace, the frontDiscordChannel
+ * shape), touching neither the interactions front nor eve's own adapter/receive. With no URL
+ * configured in the developer portal this route is simply never hit.
+ */
+export function withDiscordEventsRoute<C extends Channel<any, any, any>>(channel: C, opts: DiscordEventsOptions = {}): C {
+  return { ...channel, routes: [POST(PUBLIC_DISCORD_EVENTS_ROUTE, buildDiscordEventsHandler(opts)), ...channel.routes] };
+}

package/agent/channels/discord-front.ts

@@ -0,0 +1,355 @@
+// Approval-click front for the Discord interactions endpoint — the Discord sibling of
+// slack-front.ts's option-(c) route-fronting, for the same structural reason: eve's
+// `discordChannel` owns the interactions URL and handles MESSAGE_COMPONENT clicks itself
+// (its own HITL decode → DEFERRED_UPDATE), exposing no onComponent hook — so an
+// `oe-approval:` button click would vanish into eve's deferral. We FRONT the public URL
+// with our own route, answer OUR clicks (approvals/discord-flow.ts), and forward everything
+// else — PING, slash commands, eve's `eve_input:` HITL clicks, modal submits — to
+// discordChannel's own handler unchanged.
+//
+// The design (mirrors frontSlackChannel exactly):
+//   • The wrapped `discordChannel` is pointed at an INTERNAL route (`/eve/v1/discord/interaction`).
+//   • OUR route sits at the PUBLIC `/eve/v1/discord` (the Interactions Endpoint URL in the
+//     Discord developer portal — unchanged, so no re-registration).
+//   • Both routes live on the SAME channel object (one channel name → one session namespace),
+//     and forwarding hands eve a FRESH Request over the same raw body, so it re-verifies and
+//     dispatches exactly as if it owned the URL — we only ADD a gate, never weaken one.
+//
+// The front route:
+//   1. Buffers the RAW body ONCE (needed for BOTH signature verification AND forwarding).
+//   2. Verifies Discord's Ed25519 signature over `timestamp + rawBody` (fail-closed 401).
+//      Unlike slack-front (which had to re-implement Slack's HMAC), eve publicly exports
+//      `verifyDiscordSignature`, so the actual crypto is eve's — we only add the header
+//      plumbing + skew window around it.
+//   3. Classifies: a type-3 MESSAGE_COMPONENT whose custom_id carries our `oe-approval:`
+//      prefix (the approvals plane) or our `oe-link:` prefix (the identity-consent button,
+//      OPE-622) → OURS, answered synchronously with the interaction response the matching click
+//      handler returns; a type-2 APPLICATION_COMMAND named "oe" → OURS too (backlog item
+//      23's zero-inference slash command — see commands/core.ts), answered synchronously and
+//      NEVER forwarded to discordChannel's `onCommand`, which dispatches a full agent turn for
+//      ANY registered command name (docs/deploy/surfaces/discord.md); anything else → forward.
+
+import { POST, type Channel, type HttpRouteDefinition, type RouteHandlerArgs } from "eve/channels";
+import { verifyDiscordSignature } from "eve/channels/discord";
+import { OE_DISCORD_APPROVAL_PREFIX } from "../approvals/discord-card.js";
+import { handleDiscordApprovalInteraction, type DiscordInteractionResponse } from "../approvals/discord-flow.js";
+import { LINK_CONSENT_CLICK_PREFIX, OE_GRANT_ACTION_PREFIX, OE_INPUT_CLICK_PREFIX } from "@open-everywhere/core/agent/adapter-api.js";
+import { handleDiscordLinkConsentInteraction } from "../identity/discord-link-consent.js";
+import { handleDiscordGrantCardInteraction } from "../access/discord-grant-click.js";
+import { handleDiscordApprovalCardInteraction, type ApprovalRespondFn } from "./discord-approval-card.js";
+import { approvalCardRespondVia, OE_COMMAND_NAME, type AttachSessionForCancel } from "@open-everywhere/core/agent/adapter-api.js";
+import { handleDiscordOeCommandInteraction } from "../commands/discord-commands.js";
+
+/** An HTTP route handler — `RouteHandler` isn't a public eve export, so we mirror its shape
+ *  (same workaround as slack-front.ts). */
+type RouteHandler = (req: Request, args: RouteHandlerArgs) => Promise<Response>;
+
+/** The public URL Discord POSTs every interaction to (the app's Interactions Endpoint URL). */
+export const PUBLIC_DISCORD_ROUTE = "/eve/v1/discord";
+/** The internal path the wrapped `discordChannel` is mounted at (never hit by Discord directly). */
+export const INTERNAL_DISCORD_ROUTE = "/eve/v1/discord/interaction";
+
+// --- signature verification (Discord Ed25519) --------------------------------
+//
+// 🔴 THIS SCHEME STAYS INLINE AND IS DELIBERATELY *NOT* ON THE WEBHOOK VERIFIER REGISTRY (OPE-197).
+// Slack's `v0=` scheme was registered under that ticket; this one was assessed alongside it and
+// refused. The reason is NOT that it fails to fit `WebhookVerifier.verify({rawBody, headers, keys,
+// nowMs})` — it fits perfectly, and the registry's `keyKind: "public-key"` was designed against this
+// exact scheme. The reason is that the entry would be UNREACHABLE, and a registry row nothing can
+// reach makes the thing the registry is for WORSE:
+//
+//   • `registeredWebhookVerifierSources()` is printed verbatim in the generic ingress's 401
+//     (webhooks/gate.ts) as the set of sources a caller may declare. Adding `discord` to it would
+//     advertise a hook an operator can create, point Discord at, and never receive one delivery on.
+//   • EVERY Ed25519-signed Discord egress is bound to a RESPONSE contract the generic ingress
+//     structurally does not satisfy, so Discord refuses the endpoint before any delivery exists:
+//       – the Interactions Endpoint URL is saved only if an immediate `PING` gets a signed `PONG`
+//         body back (docs/deploy/surfaces/discord.md §1.5 and its Gotchas);
+//       – the Webhook Events URL requires "a 204 with an EMPTY body within 3s for both the PING and
+//         every event", and "repeated failures get the endpoint unregistered" (the header of
+//         channels/discord-events.ts, verified against Discord's docs).
+//     The generic ingress answers `200 "ok"` (core channels/webhooks.ts). That is neither, on either
+//     arm — and both arms are all there is: Discord has no third signed outbound.
+//
+// This is the shape OPE-207 already deleted once on the Notion side: an arm that shipped and was
+// removed because "nothing could put a hook into the status the arm required, so it was reachable by
+// no route". Registering `discord` would re-create it, one registry row further out.
+//
+// WHAT WOULD FLIP THIS: the generic ingress growing a per-source response contract (a source able to
+// declare the bytes it must answer a verification handshake with). Then the entry becomes reachable
+// and should be added — the verifier body below is already the whole implementation. Until then the
+// honest statement is that this deployment CAN verify Discord's signature, on the one route Discord
+// can actually be pointed at, which is this one.
+//
+// (Note also that the crypto here is EVE'S `verifyDiscordSignature`, not ours — this file adds
+// header plumbing and a skew window. On the "is the scheme ours and inline" axis it was always
+// closer to Linear and Teams, which use eve's verifiers, than to Slack, which does not.)
+
+const DISCORD_MAX_SKEW_SECONDS = 60 * 5; // same window eve's own verifyDiscordRequest defaults to
+
+/**
+ * Verify a Discord interaction over the RAW body (the exact bytes Discord signed):
+ * Ed25519 of `{timestamp}{body}` against the app public key, with a 5-minute skew window.
+ * Fail-closed: no key configured, a missing header, a malformed/stale timestamp, or a
+ * signature mismatch all return false — never "verified". `nowMs` is injectable so the
+ * skew window is tested; the crypto itself is eve's public `verifyDiscordSignature`.
+ */
+export function verifyDiscordInteraction(
+  rawBody: string,
+  headers: Headers,
+  publicKey: string | undefined,
+  nowMs: number = Date.now(),
+): boolean {
+  const signature = headers.get("x-signature-ed25519");
+  const timestamp = headers.get("x-signature-timestamp");
+  if (!publicKey || !signature || !timestamp) return false;
+  const ts = Number(timestamp);
+  if (!Number.isFinite(ts) || Math.abs(nowMs / 1000 - ts) > DISCORD_MAX_SKEW_SECONDS) return false;
+  return verifyDiscordSignature({ body: rawBody, publicKey, signature, timestamp });
+}
+
+/** The decision the front route makes for one verified inbound interaction. The parsed
+ *  body rides the approval-click branch so the handler needn't re-parse it. */
+export type DiscordFrontDecision =
+  | { readonly kind: "forward"; readonly reason: string }
+  | { readonly kind: "approval-click"; readonly reason: string; readonly interaction: unknown }
+  | { readonly kind: "link-consent-click"; readonly reason: string; readonly interaction: unknown }
+  /** An `oe_grant:` credential-grant card button click (core access/credential-grant-card.ts) — ours:
+   *  the OWNER answering a request to spend their credential (OPE-1260). */
+  | { readonly kind: "grant-click"; readonly reason: string; readonly interaction: unknown }
+  /** An `oe_input:` BRIDGED-APPROVAL card button click (core channels/approval-card.ts) — ours: the
+   *  room answering an eve `tool-approval` this deployment rendered onto a unified origin (OPE-1720).
+   *  eve's own route cannot resolve it — the parked request lives on the UNIFIED window, not on the
+   *  Discord channel's session — so forwarding it would drop the tap. */
+  | { readonly kind: "input-click"; readonly reason: string; readonly interaction: unknown }
+  | { readonly kind: "oe-command"; readonly reason: string; readonly interaction: unknown };
+
+/**
+ * Decide how the front route handles a raw interaction body. FORWARD is the fail-safe
+ * default: anything discordChannel owns (PING/PONG, any OTHER slash command, eve's own HITL
+ * component clicks and modal submits) or anything unrecognized goes to it unchanged.
+ * A MESSAGE_COMPONENT (type 3) whose custom_id starts with our `oe-approval:` prefix, or an
+ * APPLICATION_COMMAND (type 2) named "oe", is ours. Pure: no I/O, so every branch is
+ * unit-tested.
+ */
+export function classifyDiscordInteraction(rawBody: string): DiscordFrontDecision {
+  let json: unknown;
+  try {
+    json = JSON.parse(rawBody);
+  } catch {
+    return { kind: "forward", reason: "unparseable body — let discordChannel answer it" };
+  }
+  if (typeof json !== "object" || json === null) {
+    return { kind: "forward", reason: "non-object body — let discordChannel answer it" };
+  }
+  const p = json as Record<string, unknown>;
+  if (p.type === 2) {
+    // APPLICATION_COMMAND (a slash command). "/oe" is OUR zero-inference command (backlog
+    // item 23) — answered here, NEVER forwarded to discordChannel's onCommand, which
+    // dispatches a full agent turn for ANY registered command name. Any OTHER command name
+    // (e.g. "/ask", docs/deploy/surfaces/discord.md) is a real user command and still
+    // forwards untouched — this is the ONLY command name the front route special-cases.
+    const data = typeof p.data === "object" && p.data !== null ? (p.data as Record<string, unknown>) : undefined;
+    const name = typeof data?.name === "string" ? data.name : undefined;
+    if (name === OE_COMMAND_NAME) {
+      return { kind: "oe-command", reason: `"/${OE_COMMAND_NAME}" command — ours, zero-inference, never forwarded`, interaction: json };
+    }
+    return { kind: "forward", reason: `application command "${name ?? "?"}" — not ours, discordChannel dispatches it` };
+  }
+  if (p.type !== 3) {
+    return { kind: "forward", reason: `interaction type ${String(p.type)} — not a component click` };
+  }
+  const data = typeof p.data === "object" && p.data !== null ? (p.data as Record<string, unknown>) : undefined;
+  const customId = typeof data?.custom_id === "string" ? data.custom_id : undefined;
+  // Four OE prefixes now, and they are deliberately different strings so a log line names one
+  // feature: `oe-approval:` is the approvals plane, `oe-link:` is the identity-consent button
+  // (OPE-622), `oe_grant:` is the credential-grant card (OPE-1260 — before it, that card's buttons
+  // rendered here and fell through to eve, so the owner's tap was lost), `oe_input:` is the bridged
+  // eve approval card on a unified origin (OPE-1720 — the same lost-tap shape, one plane along).
+  // Anything else — eve's own `eve_input:` HITL buttons included — forwards untouched, and the two
+  // spellings are one character apart on purpose: `oe_input:` is OURS and `eve_input:` is eve's.
+  if (customId?.startsWith(OE_DISCORD_APPROVAL_PREFIX)) {
+    return { kind: "approval-click", reason: "oe-approval: component click — ours, never forwarded", interaction: json };
+  }
+  if (customId?.startsWith(LINK_CONSENT_CLICK_PREFIX)) {
+    return { kind: "link-consent-click", reason: "oe-link: component click — ours, never forwarded", interaction: json };
+  }
+  if (customId?.startsWith(OE_GRANT_ACTION_PREFIX)) {
+    return { kind: "grant-click", reason: "oe_grant: component click — ours, never forwarded", interaction: json };
+  }
+  if (customId?.startsWith(OE_INPUT_CLICK_PREFIX)) {
+    return { kind: "input-click", reason: "oe_input: component click — ours, never forwarded", interaction: json };
+  }
+  return { kind: "forward", reason: "component click — eve's HITL owns it" };
+}
+
+/** Injectable seams so the front route is testable without live crypto env / the real store. */
+export interface DiscordFrontOptions {
+  /** The app public key; defaults to DISCORD_PUBLIC_KEY (same env eve's channel reads). */
+  readonly publicKey?: string;
+  readonly now?: () => number;
+  /** Approval-click handler (defaults to the real approvals/discord-flow.ts). Injectable so
+   *  tests can stub it without the store/executor machinery it drags in. */
+  readonly handleApprovalInteraction?: (
+    raw: unknown,
+    deps?: { waitUntil?: (p: Promise<unknown>) => void },
+  ) => Promise<DiscordInteractionResponse | null>;
+  /** Identity-consent click handler (defaults to the real identity/discord-link-consent.ts).
+   *  Injectable for the same reason the approval one is — it reaches the link store. */
+  readonly handleLinkConsentInteraction?: (raw: unknown) => Promise<DiscordInteractionResponse | null>;
+  /** Credential-grant card click handler (defaults to the real access/discord-grant-click.ts).
+   *  Injectable for the same reason the two above are — it reaches the grant store.
+   *
+   *  🔴 IT TAKES THE ROUTE'S `waitUntil` (OPE-1282). That door answers with a DEFERRED response and
+   *  resolves the click off the response path, so it needs somewhere for that work to live past the
+   *  reply. A stub that ignores the second argument gets the old synchronous shape, which is exactly
+   *  what a test wants. */
+  readonly handleGrantCardInteraction?: (
+    raw: unknown,
+    deps?: { waitUntil?: (p: Promise<unknown>) => void },
+  ) => Promise<DiscordInteractionResponse | null>;
+  /** Bridged-approval-card `oe_input:` tap handler (OPE-1720, defaults to
+   *  `./discord-approval-card.ts`). Injectable so the classification and the branch are testable
+   *  without a store, a bot token or eve's `respond` primitive. It takes the SETTLE delivery as its
+   *  second argument because `args.from` is the only place eve hands that primitive out, so it is
+   *  bound in the route and injected rather than reached for inside the handler. */
+  readonly handleApprovalCardInteraction?: (
+    raw: unknown,
+    respond: ApprovalRespondFn,
+    deps?: { waitUntil?: (p: Promise<unknown>) => void },
+  ) => Promise<DiscordInteractionResponse | null>;
+  /** "/oe" zero-inference command handler (defaults to the real commands/discord-commands.ts).
+   *  Injectable so tests can stub it without the spend/approval/memory machinery it may touch. */
+  readonly handleOeCommand?: (raw: unknown, attachSession?: AttachSessionForCancel) => Promise<DiscordInteractionResponse | null>;
+}
+
+function interactionJson(body: DiscordInteractionResponse): Response {
+  return new Response(JSON.stringify(body), { status: 200, headers: { "content-type": "application/json" } });
+}
+
+/**
+ * Build the front route handler. Buffers the body once, verifies the Ed25519 signature,
+ * then answers our approval clicks or forwards per {@link classifyDiscordInteraction}.
+ * `innerHandler` is discordChannel's own POST handler, invoked with a FRESH Request
+ * (re-readable body) + the same {@link RouteHandlerArgs}, so discordChannel re-verifies
+ * and dispatches exactly as if it owned the URL.
+ */
+export function buildDiscordFrontHandler(innerHandler: RouteHandler, opts: DiscordFrontOptions = {}): RouteHandler {
+  const now = opts.now ?? (() => Date.now());
+  const publicKey = () => opts.publicKey ?? process.env.DISCORD_PUBLIC_KEY;
+  const handleClick = opts.handleApprovalInteraction ?? handleDiscordApprovalInteraction;
+  const handleLinkConsent = opts.handleLinkConsentInteraction ?? handleDiscordLinkConsentInteraction;
+  const handleGrantCard = opts.handleGrantCardInteraction ?? handleDiscordGrantCardInteraction;
+  const handleApprovalCard = opts.handleApprovalCardInteraction ?? handleDiscordApprovalCardInteraction;
+  const handleOeCommand = opts.handleOeCommand ?? handleDiscordOeCommandInteraction;
+
+  return async (req: Request, args: RouteHandlerArgs): Promise<Response> => {
+    const rawBody = await req.text();
+    if (!verifyDiscordInteraction(rawBody, req.headers, publicKey(), now())) {
+      return new Response("unauthorized", { status: 401 });
+    }
+    const decision = classifyDiscordInteraction(rawBody);
+
+    if (decision.kind === "approval-click") {
+      // Ours: parsed, admin-checked, CAS-decided and executed by our code (the same
+      // resolveApprovalClick core Slack clicks use), answered as an interaction response.
+      //
+      // 🔴 `args.waitUntil` RIDES ALONG (OPE-1407), for the same reason the grant branch below takes
+      // it: the decision FEEDBACK — a Discord REST notice post plus a wake dispatch — runs off the
+      // response path, and on a serverless host a promise with nowhere to live is frozen with the
+      // invocation. The door awaits the feedback when this is absent, so passing it is what moves
+      // that leg out of Discord's three-second budget.
+      const response = await handleClick(decision.interaction, { waitUntil: args.waitUntil });
+      if (response) return interactionJson(response);
+      // Defensive: classification said "ours" but the handler disagreed (an ours-prefixed
+      // but unparseable custom_id) — fall through to forwarding so the click is never
+      // silently swallowed; eve's HITL decode no-ops it with a harmless deferred ack.
+    }
+
+    if (decision.kind === "link-consent-click") {
+      // Ours: the person named in a directory-transport link request tapped their own consent ask
+      // (OPE-622). Core's `resolveLinkConsentClick` owns the decision and the writes; this route only
+      // carries Discord's verified envelope in and Discord's EPHEMERAL answer back out. A null means
+      // the handler could not read the id after all — forward rather than swallow, exactly as the
+      // approval branch does.
+      const response = await handleLinkConsent(decision.interaction);
+      if (response) return interactionJson(response);
+    }
+
+    if (decision.kind === "grant-click") {
+      // Ours: the OWNER of a credential answered a request to spend it (OPE-1260). Core's
+      // `resolveGrantCardClick` owns the decision, the owner check and the writes; this route only
+      // carries Discord's verified envelope in and Discord's EPHEMERAL answer back out. A null means
+      // the handler could not read the id after all — forward rather than swallow, exactly as the two
+      // branches above do.
+      //
+      // 🔴 `args.waitUntil` RIDES ALONG (OPE-1282), and this branch is the only one that passes it.
+      // The grant door answers with a DEFERRED response and resolves the click afterwards; without
+      // somewhere for that work to survive the reply, a serverless host would freeze the invocation
+      // and the owner would sit on "thinking…" forever. The door falls back to its old synchronous
+      // shape when this is absent, so passing it is what turns the fix on.
+      const response = await handleGrantCard(decision.interaction, { waitUntil: args.waitUntil });
+      if (response) return interactionJson(response);
+    }
+
+    if (decision.kind === "input-click") {
+      // Ours (core channels/approval-card.ts): somebody tapped a bridged eve approval this deployment
+      // rendered onto a unified origin (OPE-1720). The handler resolves the ticket, admits the tap
+      // through the SAME floor the typed answer takes, and delivers
+      // `respond([{requestId, optionId}])` to the parked WINDOW session.
+      //
+      // 🔴 THE DELIVERY GOES BY SESSION ID (OPE-1863). `args.from` is CHANNEL-LOCAL — on this route
+      // it addresses `discord:<token>`, while the parked session lives at `unified:<token>` — so the
+      // settle threw "the target session was not found" and every tap left the approval parked.
+      // `args.attachSession` dispatches by durable session id from any channel, and
+      // `approvalCardRespondVia` is the one road every surface binds. Bound HERE and injected because
+      // the route handler is the only place eve hands out either primitive.
+      //
+      // 🔴 `args.waitUntil` RIDES ALONG, for the grant branch's reason and one more of this door's
+      // own: a settle RESUMES a parked turn, and Discord does not redeliver an interaction it never
+      // saw answered — so a slow settle without the defer shows the tapper a red failure over an
+      // approval that really did settle. A null means the payload carried our prefix but not a shape
+      // the handler could read: forward rather than swallow, exactly as the three branches above do.
+      const respondToApproval: ApprovalRespondFn = approvalCardRespondVia(args.attachSession);
+      const response = await handleApprovalCard(decision.interaction, respondToApproval, { waitUntil: args.waitUntil });
+      if (response) return interactionJson(response);
+    }
+
+    if (decision.kind === "oe-command") {
+      // Ours: zero-inference — parsed, executed as pure logic (+ the approval-card path for
+      // budget raise/clear), answered synchronously as an interaction response. NEVER reaches
+      // discordChannel's onCommand (which would dispatch a full agent turn).
+      // `args.attachSession` rides along purely for "/oe stop" (OPE-418) — it is I/O-free, so
+      // passing it costs nothing on the branches that never touch it.
+      const response = await handleOeCommand(decision.interaction, args.attachSession);
+      if (response) return interactionJson(response);
+      // Defensive fallback mirrors the approval-click branch above: classification said
+      // "ours" but the handler disagreed — never silently swallow, forward instead.
+    }
+
+    // Fresh Request so discordChannel can re-read the raw body + re-verify the signature.
+    const forwarded = new Request(req.url, { method: "POST", headers: req.headers, body: rawBody });
+    return innerHandler(forwarded, args);
+  };
+}
+
+/**
+ * Compose the approval-click front route with a wrapped `discordChannel`. `inner` must have
+ * been built with `route: INTERNAL_DISCORD_ROUTE`. Returns the SAME channel value
+ * (preserving eve's internal `__kind`/adapter/receive) with the public front route
+ * prepended — so Discord's Interactions Endpoint URL hits us, and both routes share one
+ * channel name → one session namespace. (Byte-for-byte the frontSlackChannel pattern.)
+ */
+export function frontDiscordChannel<C extends Channel<any, any, any>>(inner: C, opts: DiscordFrontOptions = {}): C {
+  const innerPost = inner.routes.find(
+    (r): r is HttpRouteDefinition<any> => r.method === "POST" && r.path === INTERNAL_DISCORD_ROUTE,
+  );
+  if (!innerPost) {
+    throw new Error(
+      `frontDiscordChannel: wrapped discordChannel must be built with route: "${INTERNAL_DISCORD_ROUTE}" ` +
+        `(found paths: ${inner.routes.map((r) => r.path).join(", ")})`,
+    );
+  }
+  const front = buildDiscordFrontHandler(innerPost.handler, opts);
+  return { ...inner, routes: [POST(PUBLIC_DISCORD_ROUTE, front), ...inner.routes] };
+}