@open-mercato/channel-discord 0.6.8-develop.7090.1.4dbca7b350

package/src/modules/channel_discord/lib/interactions-dispatch.ts

@@ -0,0 +1,288 @@
+import type { InboundProcessorPayload } from '@open-mercato/core/modules/communication_channels/workers/inbound-processor'
+import type { TranslateFn } from '@open-mercato/shared/lib/i18n/context'
+import { DISCORD_MAX_BODY_LENGTH } from './capabilities'
+import type { DiscordMessageObject, DiscordRestClient, DiscordUser } from './discord-rest'
+import { buildInboundMessageJob, type GatewayChannelScope } from './gateway-bridge'
+import { DiscordInteractionType, type ParsedInteraction } from './interactions-verify'
+
+/**
+ * Everything the dispatch path needs from a verified interaction, extracted once
+ * so nothing downstream has to re-read the untrusted body.
+ *
+ * This shape crosses a queue boundary (the HTTP route must answer Discord within
+ * three seconds, so the hub write and the follow-up REST call happen in a
+ * worker), which is why it carries no credential: `token` is the interaction's
+ * own short-lived webhook credential and the bot token is re-resolved from the
+ * encrypted credential store on the other side.
+ */
+export interface DispatchableInteraction {
+  /** Interaction snowflake — also the hub's `externalMessageId`, so redelivery dedups. */
+  id: string
+  /** Interaction webhook token. Valid for 15 minutes, single interaction. */
+  token: string
+  type: number
+  applicationId: string
+  /** Discord text channel the interaction happened in. */
+  discordChannelId: string
+  guildId?: string
+  user: DiscordUser
+  /** Slash-command name, for `APPLICATION_COMMAND` / autocomplete. */
+  commandName?: string
+  /** Component / modal `custom_id`, for `MESSAGE_COMPONENT` / `MODAL_SUBMIT`. */
+  customId?: string
+  /** Human-readable rendering of what the user did — the hub message body. */
+  content: string
+  /** ISO timestamp the hub message is stamped with. */
+  timestamp: string
+}
+
+/** The interaction types this provider turns into hub messages. */
+export const DISPATCHABLE_INTERACTION_TYPES: readonly number[] = [
+  DiscordInteractionType.APPLICATION_COMMAND,
+  DiscordInteractionType.MESSAGE_COMPONENT,
+  DiscordInteractionType.MODAL_SUBMIT,
+]
+
+export function isDispatchableInteractionType(type: number): boolean {
+  return DISPATCHABLE_INTERACTION_TYPES.includes(type)
+}
+
+function readString(source: Record<string, unknown> | undefined, key: string): string | undefined {
+  const value = source?.[key]
+  return typeof value === 'string' && value.length > 0 ? value : undefined
+}
+
+function readOptionValue(option: Record<string, unknown>): string {
+  const value = option.value
+  if (value === undefined || value === null) return ''
+  if (typeof value === 'object') return JSON.stringify(value)
+  return String(value)
+}
+
+/**
+ * Flatten a slash command's options into `name:value` pairs.
+ *
+ * Discord nests subcommands and subcommand groups as options whose own `options`
+ * array holds the real arguments, so a naive one-level read renders
+ * `/support ticket:` and loses everything the user typed. Recursion is bounded by
+ * Discord's own two-level nesting limit.
+ */
+function renderCommandOptions(options: unknown): string[] {
+  if (!Array.isArray(options)) return []
+  const rendered: string[] = []
+  for (const entry of options) {
+    if (!entry || typeof entry !== 'object') continue
+    const option = entry as Record<string, unknown>
+    const name = readString(option, 'name')
+    if (!name) continue
+    const nested = renderCommandOptions(option.options)
+    if (nested.length > 0) {
+      rendered.push(name, ...nested)
+      continue
+    }
+    rendered.push(`${name}:${readOptionValue(option)}`)
+  }
+  return rendered
+}
+
+/** Values a select menu returned, or the fields a modal submitted. */
+function renderComponentValues(data: Record<string, unknown> | undefined): string[] {
+  if (!data) return []
+  const values = data.values
+  if (Array.isArray(values)) return values.map((value) => String(value))
+
+  // Modal submissions nest one input per action row.
+  const rows = data.components
+  if (!Array.isArray(rows)) return []
+  const rendered: string[] = []
+  for (const row of rows) {
+    const children = (row as { components?: unknown } | null)?.components
+    if (!Array.isArray(children)) continue
+    for (const child of children) {
+      if (!child || typeof child !== 'object') continue
+      const field = child as Record<string, unknown>
+      const customId = readString(field, 'custom_id')
+      const value = readString(field, 'value')
+      if (!customId) continue
+      rendered.push(`${customId}:${value ?? ''}`)
+    }
+  }
+  return rendered
+}
+
+/**
+ * Render an interaction as the text a human reading the hub inbox needs.
+ *
+ * A slash command becomes `/support message:the printer is jammed`; a button or
+ * select becomes `[component] escalate` plus any selected values. The hub stores
+ * the full interaction object in `channelPayload`, so this is a readable summary
+ * rather than the record of truth.
+ */
+export function renderInteractionContent(interaction: ParsedInteraction): string {
+  const data = interaction.data
+  const commandName = readString(data, 'name')
+  const customId = readString(data, 'custom_id')
+
+  let rendered: string
+  if (interaction.type === DiscordInteractionType.APPLICATION_COMMAND) {
+    rendered = [`/${commandName ?? 'command'}`, ...renderCommandOptions(data?.options)].join(' ')
+  } else if (interaction.type === DiscordInteractionType.MESSAGE_COMPONENT) {
+    rendered = [`[component] ${customId ?? 'unknown'}`, ...renderComponentValues(data)].join(' ')
+  } else if (interaction.type === DiscordInteractionType.MODAL_SUBMIT) {
+    rendered = [`[modal] ${customId ?? 'unknown'}`, ...renderComponentValues(data)].join(' ')
+  } else {
+    rendered = `[interaction ${interaction.type}]`
+  }
+
+  return rendered.length > DISCORD_MAX_BODY_LENGTH ? rendered.slice(0, DISCORD_MAX_BODY_LENGTH) : rendered
+}
+
+/**
+ * Narrow a verified interaction to the fields the dispatch needs, or `null` when
+ * the payload cannot be dispatched at all.
+ *
+ * Returning `null` is not a rejection of the *caller* — the signature already
+ * verified — it means Discord sent a shape this provider cannot turn into a hub
+ * message (no channel, no invoking user, no follow-up token). The route answers
+ * those with a visible message rather than a deferred ack it could never
+ * replace.
+ */
+export function readDispatchableInteraction(
+  interaction: ParsedInteraction,
+  options?: { now?: Date },
+): DispatchableInteraction | null {
+  if (!isDispatchableInteractionType(interaction.type)) return null
+
+  const id = typeof interaction.id === 'string' && interaction.id.length > 0 ? interaction.id : null
+  const token = typeof interaction.token === 'string' && interaction.token.length > 0 ? interaction.token : null
+  const applicationId =
+    typeof interaction.application_id === 'string' && interaction.application_id.length > 0
+      ? interaction.application_id
+      : null
+  const discordChannelId =
+    typeof interaction.channel_id === 'string' && interaction.channel_id.length > 0 ? interaction.channel_id : null
+  // A guild interaction carries the invoker under `member.user`; a DM carries it
+  // directly under `user`.
+  const rawUser = interaction.member?.user ?? interaction.user
+  const userId = typeof rawUser?.id === 'string' && rawUser.id.length > 0 ? rawUser.id : null
+
+  if (!id || !token || !applicationId || !discordChannelId || !userId) return null
+
+  return {
+    id,
+    token,
+    type: interaction.type,
+    applicationId,
+    discordChannelId,
+    guildId: typeof interaction.guild_id === 'string' ? interaction.guild_id : undefined,
+    user: {
+      id: userId,
+      username: rawUser?.username ?? userId,
+      global_name: rawUser?.global_name ?? null,
+    },
+    commandName: readString(interaction.data, 'name'),
+    customId: readString(interaction.data, 'custom_id'),
+    content: renderInteractionContent(interaction),
+    timestamp: (options?.now ?? new Date()).toISOString(),
+  }
+}
+
+/**
+ * Present the interaction as the raw Discord message object the hub's inbound
+ * path already understands.
+ *
+ * WHY A SYNTHESIZED MESSAGE: the hub contract stays untouched. The inbound
+ * processor calls `adapter.normalizeInbound` on whatever `raw` it is handed, so
+ * shaping the interaction like a message means a slash command lands in the same
+ * conversation, under the same tenant scope, with the same dedup key discipline
+ * as anything typed in the channel — no hub-side special case for interactions.
+ */
+export function buildInteractionMessage(dispatch: DispatchableInteraction): DiscordMessageObject {
+  return {
+    id: dispatch.id,
+    channel_id: dispatch.discordChannelId,
+    guild_id: dispatch.guildId,
+    content: dispatch.content,
+    author: dispatch.user,
+    timestamp: dispatch.timestamp,
+    discord_interaction: {
+      id: dispatch.id,
+      type: dispatch.type,
+      applicationId: dispatch.applicationId,
+      commandName: dispatch.commandName,
+      customId: dispatch.customId,
+    },
+  }
+}
+
+/**
+ * Build the hub inbound-processor job for a dispatchable interaction — the same
+ * job shape, on the same queue, that the gateway worker produces for a typed
+ * message. Returns `null` when the interaction was invoked by a bot (the
+ * feedback-loop guard `buildInboundMessageJob` owns).
+ */
+export function buildInteractionInboundJob(input: {
+  dispatch: DispatchableInteraction
+  channel: GatewayChannelScope
+  botUserId?: string
+}): InboundProcessorPayload | null {
+  return buildInboundMessageJob({
+    message: buildInteractionMessage(input.dispatch),
+    channel: input.channel,
+    botUserId: input.botUserId,
+  })
+}
+
+/**
+ * Copy shown to the user in Discord once the interaction has been recorded.
+ *
+ * Takes the translator rather than resolving one, so the pure builder stays
+ * usable from the worker, from the route and from a test with no module
+ * registry. Each key carries its English fallback: a worker process that never
+ * loaded the app dictionaries must still say something a human can read, not
+ * echo a translation key back into a Discord channel.
+ */
+export function buildInteractionFollowUpContent(dispatch: DispatchableInteraction, t: TranslateFn): string {
+  if (dispatch.type === DiscordInteractionType.APPLICATION_COMMAND) {
+    return t(
+      'channel_discord.interactions.commandReceived',
+      'Received — `/{command}` is now in the Open Mercato inbox and someone will pick it up from there.',
+      { command: dispatch.commandName ?? '' },
+    )
+  }
+  return t(
+    'channel_discord.interactions.componentReceived',
+    'Received — your response is now in the Open Mercato inbox and someone will pick it up from there.',
+  )
+}
+
+/**
+ * Replace the deferred acknowledgement with a real message.
+ *
+ * ORDER MATTERS: editing the original response is what actually ends Discord's
+ * "thinking…" state, so it is tried first. A follow-up POST is the fallback for
+ * the case where the original response is already gone (Discord answers 404),
+ * which still gets the user a visible answer instead of a spinner that never
+ * resolves.
+ *
+ * Returns which call delivered the message so the worker can log it; throws only
+ * when neither did, letting the queue's retry policy have another go inside the
+ * interaction token's 15-minute lifetime.
+ */
+export async function sendInteractionFollowUp(
+  client: DiscordRestClient,
+  input: { applicationId: string; interactionToken: string; content: string; ephemeral?: boolean },
+): Promise<'edited-original' | 'follow-up'> {
+  const body = { content: input.content, ephemeral: input.ephemeral }
+  try {
+    await client.editOriginalInteractionResponse(input.applicationId, input.interactionToken, body)
+    return 'edited-original'
+  } catch (editError) {
+    try {
+      await client.createInteractionFollowUp(input.applicationId, input.interactionToken, body)
+      return 'follow-up'
+    } catch {
+      throw editError
+    }
+  }
+}

package/src/modules/channel_discord/lib/interactions-handler.ts

@@ -0,0 +1,267 @@
+import { DISCORD_MESSAGE_FLAG_EPHEMERAL } from './discord-rest'
+import {
+  isDispatchableInteractionType,
+  readDispatchableInteraction,
+  type DispatchableInteraction,
+} from './interactions-dispatch'
+import {
+  DiscordInteractionResponseType,
+  DiscordInteractionType,
+  hasVerifiableSignatureHeaders,
+  isSignatureTimestampFresh,
+  parseInteractionBody,
+  readInteractionApplicationId,
+  verifyDiscordSignature,
+  type TimestampFreshnessOptions,
+} from './interactions-verify'
+
+export interface InteractionCandidate {
+  channelId: string
+  /** Hub channel type, carried through so the dispatch job matches the gateway's. */
+  channelType: string
+  tenantId: string
+  organizationId: string | null
+  publicKey: string
+  /** Discord application this channel's bot belongs to; `null` when unknown. */
+  applicationId: string | null
+  /**
+   * Scope `integrationCredentialsService.resolve` must be called with to obtain
+   * this channel's bot token. Carried instead of the token itself so no
+   * credential ever reaches a queue payload.
+   */
+  credentialScope: { tenantId: string; organizationId: string; userId: string | null }
+}
+
+/**
+ * The two user-visible strings the synchronous handler can have to emit.
+ *
+ * They are passed in rather than translated here so the handler stays pure and
+ * synchronous — Discord gives the endpoint three seconds, and the caller already
+ * knows the locale.
+ */
+export interface InteractionMessages {
+  /** Verified, but the payload carries no channel / user / token to dispatch. */
+  notDispatchable: string
+  /** Verified and well-formed, but this provider does not handle the type. */
+  unsupported: string
+}
+
+export const DEFAULT_INTERACTION_MESSAGES: InteractionMessages = {
+  notDispatchable:
+    'This interaction is missing the channel or user context Open Mercato needs, so it was not recorded.',
+  unsupported: 'The Open Mercato Discord channel does not handle this interaction type.',
+}
+
+function ephemeralReply(content: string): Record<string, unknown> {
+  return {
+    type: DiscordInteractionResponseType.CHANNEL_MESSAGE_WITH_SOURCE,
+    data: { content, flags: DISCORD_MESSAGE_FLAG_EPHEMERAL },
+  }
+}
+
+/**
+ * What the candidate loader is allowed to narrow by. `applicationId` comes from
+ * the unverified request body, so it may only ever shrink the candidate set —
+ * see `readInteractionApplicationId`.
+ */
+export interface InteractionCandidateFilter {
+  applicationId: string | null
+}
+
+export interface InteractionResult {
+  status: number
+  /** JSON body to return (Discord expects a response type for verified interactions). */
+  body: Record<string, unknown>
+  /** The channel the signature verified against (tenant-pinned). Null on reject. */
+  matchedChannel: InteractionCandidate | null
+  /**
+   * Work the caller MUST hand off when the body above is a deferred
+   * acknowledgement. Non-null exactly when the response promises a follow-up:
+   * ignoring it is what leaves the user staring at "thinking…" forever.
+   */
+  dispatch?: DispatchableInteraction | null
+}
+
+/**
+ * Request-only rejection gate, evaluated before anything tenant-scoped is loaded.
+ *
+ * WHY IT EXISTS: this endpoint is unauthenticated by design, so any caller can
+ * POST to it. Everything decidable from the request alone — a missing, malformed
+ * or wrong-length signature header, a missing or stale timestamp — is decided
+ * here, so that traffic never reaches the candidate loader and never costs a
+ * database round-trip or a credential decrypt.
+ *
+ * Returns the rejection to send, or `null` when the request is well-formed
+ * enough that candidates must be loaded to answer it. It is deliberately
+ * signature-*shape* only: whether the signature actually verifies still requires
+ * a public key, and that check stays where it was.
+ */
+export function screenInteractionRequest(input: {
+  signatureHex: string | undefined | null
+  timestamp: string | undefined | null
+  freshness?: TimestampFreshnessOptions
+}): InteractionResult | null {
+  const { signatureHex, timestamp, freshness } = input
+
+  if (!isSignatureTimestampFresh(timestamp, freshness)) {
+    return { status: 401, body: { error: 'stale_timestamp' }, matchedChannel: null }
+  }
+  if (!hasVerifiableSignatureHeaders(signatureHex, timestamp)) {
+    return { status: 401, body: { error: 'invalid_signature' }, matchedChannel: null }
+  }
+  return null
+}
+
+/**
+ * Screen the request, then load only the candidates that could plausibly match
+ * it, then dispatch.
+ *
+ * This is the order the HTTP route must follow, expressed once and injectable so
+ * it can be tested without a database: `loadCandidates` is not called at all for
+ * a request the screening gate rejects, and when it is called it receives the
+ * `application_id` narrowing so the Ed25519 fan-out runs over the channels of
+ * one Discord application instead of every Discord channel in the installation.
+ *
+ * The narrowing is a NARROWING, never an authorization decision — the signature
+ * gate below is unchanged, so a body that claims someone else's `application_id`
+ * still fails unless it also carries that application's signature.
+ */
+export async function resolveDiscordInteraction(input: {
+  rawBody: string
+  signatureHex: string | undefined | null
+  timestamp: string | undefined | null
+  loadCandidates: (filter: InteractionCandidateFilter) => Promise<InteractionCandidate[]>
+  freshness?: TimestampFreshnessOptions
+  messages?: InteractionMessages
+}): Promise<InteractionResult> {
+  const { rawBody, signatureHex, timestamp, loadCandidates, freshness, messages } = input
+
+  const screened = screenInteractionRequest({ signatureHex, timestamp, freshness })
+  if (screened) return screened
+
+  const candidates = await loadCandidates({ applicationId: readInteractionApplicationId(rawBody) })
+  return handleDiscordInteraction({ rawBody, signatureHex, timestamp, candidates, freshness, messages })
+}
+
+/**
+ * Core Discord Interactions dispatch — pure and testable (no HTTP/DB).
+ *
+ * SECURITY (fail-closed): the request is rejected (401) unless its Ed25519
+ * signature verifies against exactly one candidate channel's public key. The
+ * matched channel pins the tenant, so one tenant's interaction never lands in
+ * another tenant's scope. A tampered / missing signature verifies against no
+ * candidate → 401, and no tenant-scoped work is done.
+ *
+ * REPLAY GUARD: the signed timestamp must be within
+ * `DISCORD_SIGNATURE_MAX_SKEW_SECONDS` of the server clock. The check runs
+ * BEFORE the per-candidate Ed25519 fan-out, so a replayed capture (still
+ * cryptographically valid forever) is rejected without any verify work.
+ *
+ * COST: this function only decides what to do with candidates it is handed.
+ * Callers that have to *load* those candidates first must run
+ * `screenInteractionRequest` before doing so — that is what keeps an unsigned or
+ * stale request genuinely constant-cost rather than merely cheap after the
+ * database has already been read (`resolveDiscordInteraction` does it for them).
+ *
+ * On the mandatory PING (type 1) handshake it returns `{ type: 1 }` (PONG) so
+ * Discord accepts the endpoint URL.
+ *
+ * Application commands, message components and modal submissions return a
+ * deferred acknowledgement TOGETHER WITH the `dispatch` the caller must hand to
+ * the interactions worker: that worker normalizes the interaction into the hub's
+ * existing inbound path and replaces the deferred ack with a real message. The
+ * two travel in one result on purpose — a deferred ack nobody follows up is the
+ * permanent "thinking…" state this endpoint used to produce.
+ *
+ * Autocomplete is answered synchronously with an empty choice list, the only
+ * response Discord accepts for it, and anything else gets a visible, ephemeral
+ * "not handled" reply rather than a promise this provider cannot keep.
+ */
+export function handleDiscordInteraction(input: {
+  rawBody: string
+  signatureHex: string | undefined | null
+  timestamp: string | undefined | null
+  candidates: InteractionCandidate[]
+  freshness?: TimestampFreshnessOptions
+  messages?: InteractionMessages
+}): InteractionResult {
+  const { rawBody, signatureHex, timestamp, candidates, freshness } = input
+  const messages = input.messages ?? DEFAULT_INTERACTION_MESSAGES
+
+  const screened = screenInteractionRequest({ signatureHex, timestamp, freshness })
+  if (screened) return screened
+
+  let matched: InteractionCandidate | null = null
+  for (const candidate of candidates) {
+    const ok = verifyDiscordSignature({
+      publicKeyHex: candidate.publicKey,
+      signatureHex,
+      timestamp,
+      rawBody,
+    })
+    if (ok) {
+      matched = candidate
+      break
+    }
+  }
+
+  if (!matched) {
+    // FAIL-CLOSED — never acknowledge an unverified interaction.
+    return { status: 401, body: { error: 'invalid_signature' }, matchedChannel: null }
+  }
+
+  const interaction = parseInteractionBody(rawBody)
+  if (!interaction) {
+    return { status: 400, body: { error: 'invalid_interaction' }, matchedChannel: matched }
+  }
+
+  if (interaction.type === DiscordInteractionType.PING) {
+    return {
+      status: 200,
+      body: { type: DiscordInteractionResponseType.PONG },
+      matchedChannel: matched,
+    }
+  }
+
+  if (isDispatchableInteractionType(interaction.type)) {
+    const dispatch = readDispatchableInteraction(interaction)
+    if (!dispatch) {
+      // Deferring here would be a promise we cannot keep: without the follow-up
+      // token or the channel there is nothing to edit the placeholder with.
+      return {
+        status: 200,
+        body: ephemeralReply(messages.notDispatchable),
+        matchedChannel: matched,
+        dispatch: null,
+      }
+    }
+    return {
+      status: 200,
+      body: { type: DiscordInteractionResponseType.DEFERRED_CHANNEL_MESSAGE_WITH_SOURCE },
+      matchedChannel: matched,
+      dispatch,
+    }
+  }
+
+  if (interaction.type === DiscordInteractionType.APPLICATION_COMMAND_AUTOCOMPLETE) {
+    // Discord rejects a deferred ack for autocomplete. No command this provider
+    // registers declares an autocompleting option, so an empty list is the
+    // honest answer and it closes the request immediately.
+    return {
+      status: 200,
+      body: {
+        type: DiscordInteractionResponseType.APPLICATION_COMMAND_AUTOCOMPLETE_RESULT,
+        data: { choices: [] },
+      },
+      matchedChannel: matched,
+      dispatch: null,
+    }
+  }
+
+  return {
+    status: 200,
+    body: ephemeralReply(messages.unsupported),
+    matchedChannel: matched,
+    dispatch: null,
+  }
+}

package/src/modules/channel_discord/lib/interactions-queue.ts

@@ -0,0 +1,52 @@
+import { createModuleQueue, type Queue } from '@open-mercato/queue'
+import type { DispatchableInteraction } from './interactions-dispatch'
+
+/**
+ * Queue carrying verified Discord interactions from the HTTP route to the
+ * dispatch worker.
+ *
+ * It lives here rather than in the worker so the route never imports a worker
+ * module: `workers/` is an auto-discovery path, and a route that pulled one in
+ * would drag the worker's dependency graph into the request bundle.
+ *
+ * Mirrors the hub's `getCommunicationChannelsQueue` — one memoized instance per
+ * name, so the route and the worker share it instead of constructing a queue per
+ * request.
+ */
+export const CHANNEL_DISCORD_INTERACTIONS_QUEUE = 'channel_discord_interactions'
+
+const INTERACTIONS_QUEUE_CONCURRENCY = 5
+
+export type InteractionDispatchJobPayload = {
+  channelId: string
+  channelType: string
+  tenantId: string
+  organizationId: string | null
+  /**
+   * Scope the **bot token** is re-resolved with on the worker side. The bot token
+   * itself is deliberately absent, because the local queue strategy persists
+   * payloads to disk as plain JSON and that token is long-lived.
+   *
+   * This is not a blanket "no credential travels on this payload" guarantee, and
+   * reading it as one would be a mistake: `interaction.token` below IS a
+   * credential. It is Discord's interaction webhook token, and on its own — with
+   * no bot token at all — it can post as the application (the `auth === null`
+   * calls in `discord-rest.ts`), so it does land on disk under the local
+   * strategy. Discord expires it 15 minutes after the interaction, which bounds
+   * the exposure rather than removing it. `interactions-dispatch.ts` states the
+   * same constraint from the other side.
+   */
+  credentialScope: { tenantId: string; organizationId: string; userId: string | null }
+  interaction: DispatchableInteraction
+}
+
+let cachedQueue: Queue<Record<string, unknown>> | null = null
+
+export function getInteractionDispatchQueue(): Queue<Record<string, unknown>> {
+  if (!cachedQueue) {
+    cachedQueue = createModuleQueue<Record<string, unknown>>(CHANNEL_DISCORD_INTERACTIONS_QUEUE, {
+      concurrency: INTERACTIONS_QUEUE_CONCURRENCY,
+    })
+  }
+  return cachedQueue
+}