@vellumai/assistant 0.4.26 → 0.4.30

package/src/runtime/routes/inbound-stages/acl-enforcement.ts

@@ -0,0 +1,880 @@
+/**
+ * Ingress ACL enforcement stage: resolves the inbound actor to a member
+ * record, enforces allow/deny/escalate policies, handles invite token
+ * intercepts, and notifies the guardian of denied access requests.
+ *
+ * Extracted from inbound-message-handler.ts to keep the top-level handler
+ * focused on orchestration.
+ */
+import type { ChannelId } from "../../../channels/types.js";
+import { findContactChannel } from "../../../contacts/contact-store.js";
+import { touchChannelLastSeen } from "../../../contacts/contacts-write.js";
+import type {
+  ChannelStatus,
+  ContactChannel,
+  ContactWithChannels,
+  MemberStatus,
+} from "../../../contacts/types.js";
+import * as channelDeliveryStore from "../../../memory/channel-delivery-store.js";
+import { getLogger } from "../../../util/logger.js";
+import { notifyGuardianOfAccessRequest } from "../../access-request-helper.js";
+import {
+  createOutboundSession,
+  findActiveSession,
+  getPendingChallenge,
+  resolveBootstrapToken,
+} from "../../channel-guardian-service.js";
+import { getTransport } from "../../channel-invite-transport.js";
+import { deliverChannelReply } from "../../gateway-client.js";
+import { redeemInvite } from "../../invite-redemption-service.js";
+import { getInviteRedemptionReply } from "../../invite-redemption-templates.js";
+
+const log = getLogger("runtime-http");
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export interface AclEnforcementParams {
+  canonicalSenderId: string | null;
+  hasSenderIdentityClaim: boolean;
+  rawSenderId: string | undefined;
+  sourceChannel: ChannelId;
+  conversationExternalId: string;
+  canonicalAssistantId: string;
+  trimmedContent: string;
+  sourceMetadata: Record<string, unknown> | undefined;
+  actorDisplayName: string | undefined;
+  actorUsername: string | undefined;
+  replyCallbackUrl: string | undefined;
+  mintBearerToken: () => string;
+  assistantId: string;
+  externalMessageId: string;
+}
+
+/** Resolved contact + channel pair from ACL enforcement. */
+export type ResolvedMember = {
+  contact: ContactWithChannels;
+  channel: ContactChannel;
+};
+
+export interface AclResult {
+  resolvedMember: ResolvedMember | null;
+  /** When set, the caller must return this response immediately. */
+  earlyResponse?: Response;
+  /**
+   * Parsed guardian verification code from the message content, if any.
+   * Surfaced here so downstream verification intercept logic can use it
+   * without re-parsing.
+   */
+  guardianVerifyCode: string | undefined;
+}
+
+/**
+ * Parse a guardian verification code from message content.
+ * Accepts a bare code as the entire message: 6-digit numeric OR 64-char hex
+ * (hex is retained for compatibility with unbound inbound/bootstrap sessions
+ * that intentionally use high-entropy secrets).
+ */
+function parseGuardianVerifyCode(content: string): string | undefined {
+  const bareMatch = content.match(/^([0-9a-fA-F]{64}|\d{6})$/);
+  if (bareMatch) return bareMatch[1];
+
+  return undefined;
+}
+
+/** Map ChannelStatus to the legacy MemberStatus for API consumers. */
+export function channelStatusToMemberStatus(
+  status: ChannelStatus,
+): MemberStatus {
+  if (status === "unverified") return "pending";
+  return status;
+}
+
+/**
+ * Enforce ingress ACL rules: member lookup, non-member/inactive denial,
+ * policy enforcement (allow/deny/escalate bypass), invite token intercepts,
+ * and guardian notification for denied access.
+ */
+export async function enforceIngressAcl(
+  params: AclEnforcementParams,
+): Promise<AclResult> {
+  const {
+    canonicalSenderId,
+    hasSenderIdentityClaim,
+    rawSenderId,
+    sourceChannel,
+    conversationExternalId,
+    canonicalAssistantId,
+    trimmedContent,
+    sourceMetadata,
+    actorDisplayName,
+    actorUsername,
+    replyCallbackUrl,
+    mintBearerToken,
+    assistantId,
+    externalMessageId,
+  } = params;
+
+  let resolvedMember: ResolvedMember | null = null;
+
+  // Verification codes must bypass the ACL membership check — users without a
+  // member record need to verify before they can be recognized as members.
+  const guardianVerifyCode = parseGuardianVerifyCode(trimmedContent);
+  const isGuardianVerifyCode = guardianVerifyCode !== undefined;
+
+  // /start gv_<token> bootstrap commands must also bypass ACL — the user
+  // hasn't been verified yet and needs to complete the bootstrap handshake.
+  const rawCommandIntentForAcl = sourceMetadata?.commandIntent;
+  const isBootstrapCommand =
+    rawCommandIntentForAcl &&
+    typeof rawCommandIntentForAcl === "object" &&
+    !Array.isArray(rawCommandIntentForAcl) &&
+    (rawCommandIntentForAcl as Record<string, unknown>).type === "start" &&
+    typeof (rawCommandIntentForAcl as Record<string, unknown>).payload ===
+      "string" &&
+    (
+      (rawCommandIntentForAcl as Record<string, unknown>).payload as string
+    ).startsWith("gv_");
+
+  // Parse invite token from /start payloads using the channel transport
+  // adapter. The token is extracted once here so both the ACL bypass and
+  // the intercept handler can reference it without re-parsing.
+  const commandIntentForAcl =
+    rawCommandIntentForAcl &&
+    typeof rawCommandIntentForAcl === "object" &&
+    !Array.isArray(rawCommandIntentForAcl)
+      ? (rawCommandIntentForAcl as Record<string, unknown>)
+      : undefined;
+  const inviteTransport = getTransport(sourceChannel);
+  const inviteToken = inviteTransport?.extractInboundToken({
+    commandIntent: commandIntentForAcl,
+    content: trimmedContent,
+    sourceMetadata,
+  });
+
+  if (canonicalSenderId || hasSenderIdentityClaim) {
+    // Only perform member lookup when we have a usable canonical ID.
+    // Whitespace-only senders (hasSenderIdentityClaim=true but
+    // canonicalSenderId=null) skip the lookup and fall into the deny path.
+    if (canonicalSenderId) {
+      const contactResult = findContactChannel({
+        channelType: sourceChannel,
+        externalUserId: canonicalSenderId,
+        externalChatId: conversationExternalId,
+      });
+      resolvedMember = contactResult
+        ? {
+            contact: contactResult.contact,
+            channel: contactResult.channel,
+          }
+        : null;
+    }
+
+    if (!resolvedMember) {
+      // Determine whether a verification-code bypass is warranted: only allow
+      // when there is a pending (unconsumed, unexpired) challenge AND no
+      // active guardian binding for this (assistantId, channel).
+      let denyNonMember = true;
+      if (isGuardianVerifyCode) {
+        // Allow bypass when there is any consumable challenge or active
+        // outbound session.  The !hasActiveBinding guard is intentionally
+        // omitted: rebind sessions create a consumable challenge while a
+        // binding already exists, and the identity check inside
+        // validateAndConsumeChallenge prevents unauthorized takeovers.
+        const hasPendingChallenge = !!getPendingChallenge(
+          canonicalAssistantId,
+          sourceChannel,
+        );
+        const hasActiveOutboundSession = !!findActiveSession(
+          canonicalAssistantId,
+          sourceChannel,
+        );
+        if (hasPendingChallenge || hasActiveOutboundSession) {
+          denyNonMember = false;
+        } else {
+          log.info(
+            { sourceChannel, hasPendingChallenge, hasActiveOutboundSession },
+            "Ingress ACL: guardian verification bypass denied",
+          );
+        }
+      }
+
+      // Bootstrap deep-link commands bypass ACL only when the token
+      // resolves to a real pending_bootstrap session. Without this check,
+      // any `/start gv_<garbage>` would bypass the not_a_member gate and
+      // fall through to normal /start processing.
+      if (isBootstrapCommand) {
+        const bootstrapPayload = (
+          rawCommandIntentForAcl as Record<string, unknown>
+        ).payload as string;
+        const bootstrapTokenForAcl = bootstrapPayload.slice(3); // strip 'gv_' prefix
+        const bootstrapSessionForAcl = resolveBootstrapToken(
+          canonicalAssistantId,
+          sourceChannel,
+          bootstrapTokenForAcl,
+        );
+        if (
+          bootstrapSessionForAcl &&
+          bootstrapSessionForAcl.status === "pending_bootstrap"
+        ) {
+          denyNonMember = false;
+        } else {
+          log.info(
+            { sourceChannel, hasValidBootstrapSession: false },
+            "Ingress ACL: bootstrap command bypass denied — no valid pending_bootstrap session",
+          );
+        }
+      }
+
+      // ── Invite token intercept (non-member) ──
+      // /start invite deep links grant access without guardian approval.
+      // Intercept here — before the deny gate — so valid invites short-circuit
+      // the ACL rejection and never reach the agent pipeline.
+      if (inviteToken && denyNonMember) {
+        const inviteResult = await handleInviteTokenIntercept({
+          rawToken: inviteToken,
+          sourceChannel,
+          externalChatId: conversationExternalId,
+          externalMessageId,
+          senderExternalUserId: canonicalSenderId ?? rawSenderId,
+          senderName: actorDisplayName,
+          senderUsername: actorUsername,
+          replyCallbackUrl,
+          bearerToken: mintBearerToken(),
+          assistantId,
+          canonicalAssistantId,
+        });
+        if (inviteResult)
+          return {
+            resolvedMember: null,
+            earlyResponse: inviteResult,
+            guardianVerifyCode,
+          };
+      }
+
+      if (denyNonMember) {
+        log.info(
+          { sourceChannel, externalUserId: canonicalSenderId },
+          "Ingress ACL: no member record, denying",
+        );
+
+        // Slack-specific: send a verification challenge directly to the
+        // user's DM instead of requiring guardian-mediated approval. The
+        // user can reply with the code in the DM to self-verify.
+        if (sourceChannel === "slack" && (canonicalSenderId ?? rawSenderId)) {
+          const slackVerifyResult = initiateSlackVerificationChallenge({
+            canonicalAssistantId,
+            sourceChannel,
+            conversationExternalId,
+            senderUserId: (canonicalSenderId ?? rawSenderId)!,
+            replyCallbackUrl,
+            mintBearerToken,
+            assistantId,
+          });
+
+          if (slackVerifyResult.initiated) {
+            // Still notify the guardian about the access attempt
+            try {
+              notifyGuardianOfAccessRequest({
+                canonicalAssistantId,
+                sourceChannel,
+                conversationExternalId,
+                actorExternalId: canonicalSenderId ?? rawSenderId,
+                actorDisplayName,
+                actorUsername,
+              });
+            } catch (err) {
+              log.error(
+                { err, sourceChannel, conversationExternalId },
+                "Failed to notify guardian of access request (Slack verification)",
+              );
+            }
+
+            if (replyCallbackUrl) {
+              try {
+                await deliverChannelReply(
+                  replyCallbackUrl,
+                  {
+                    chatId: conversationExternalId,
+                    text: "I've notified the owner. They'll share a verification code with you if they approve access.",
+                    assistantId,
+                  },
+                  mintBearerToken(),
+                );
+              } catch (err) {
+                log.error(
+                  { err, conversationExternalId },
+                  "Failed to deliver Slack verification prompt reply",
+                );
+              }
+            }
+
+            return {
+              resolvedMember: null,
+              earlyResponse: Response.json({
+                accepted: true,
+                denied: true,
+                reason: "verification_challenge_sent",
+                verificationSessionId: slackVerifyResult.sessionId,
+              }),
+              guardianVerifyCode,
+            };
+          }
+        }
+
+        // Notify the guardian about the access request so they can approve/deny.
+        // Uses the shared helper which handles guardian binding lookup,
+        // deduplication, canonical request creation, and notification emission.
+        let guardianNotified = false;
+        try {
+          const accessResult = notifyGuardianOfAccessRequest({
+            canonicalAssistantId,
+            sourceChannel,
+            conversationExternalId,
+            actorExternalId: canonicalSenderId ?? rawSenderId,
+            actorDisplayName,
+            actorUsername,
+          });
+          guardianNotified = accessResult.notified;
+        } catch (err) {
+          log.error(
+            { err, sourceChannel, conversationExternalId },
+            "Failed to notify guardian of access request",
+          );
+        }
+
+        if (replyCallbackUrl) {
+          const replyText = guardianNotified
+            ? "Hmm looks like you don't have access to talk to me. I'll let them know you tried talking to me and get back to you."
+            : "Sorry, you haven't been approved to message this assistant.";
+          try {
+            await deliverChannelReply(
+              replyCallbackUrl,
+              {
+                chatId: conversationExternalId,
+                text: replyText,
+                assistantId,
+              },
+              mintBearerToken(),
+            );
+          } catch (err) {
+            log.error(
+              { err, conversationExternalId },
+              "Failed to deliver ACL rejection reply",
+            );
+          }
+        }
+
+        return {
+          resolvedMember: null,
+          earlyResponse: Response.json({
+            accepted: true,
+            denied: true,
+            reason: "not_a_member",
+          }),
+          guardianVerifyCode,
+        };
+      }
+    }
+
+    if (resolvedMember) {
+      if (resolvedMember.channel.status !== "active") {
+        // Same bypass logic as the no-member branch: verification codes and
+        // bootstrap commands must pass through even when the member record is
+        // revoked/blocked — otherwise the user can never re-verify.
+        let denyInactiveMember = true;
+        if (isGuardianVerifyCode) {
+          const hasPendingChallenge = !!getPendingChallenge(
+            canonicalAssistantId,
+            sourceChannel,
+          );
+          const hasActiveOutboundSession = !!findActiveSession(
+            canonicalAssistantId,
+            sourceChannel,
+          );
+          if (hasPendingChallenge || hasActiveOutboundSession) {
+            denyInactiveMember = false;
+          } else {
+            log.info(
+              {
+                sourceChannel,
+                channelId: resolvedMember.channel.id,
+                hasPendingChallenge,
+                hasActiveOutboundSession,
+              },
+              "Ingress ACL: inactive member verification bypass denied",
+            );
+          }
+        }
+        if (isBootstrapCommand) {
+          const bootstrapPayload = (
+            rawCommandIntentForAcl as Record<string, unknown>
+          ).payload as string;
+          const bootstrapTokenForAcl = bootstrapPayload.slice(3);
+          const bootstrapSessionForAcl = resolveBootstrapToken(
+            canonicalAssistantId,
+            sourceChannel,
+            bootstrapTokenForAcl,
+          );
+          if (
+            bootstrapSessionForAcl &&
+            bootstrapSessionForAcl.status === "pending_bootstrap"
+          ) {
+            denyInactiveMember = false;
+          } else {
+            log.info(
+              {
+                sourceChannel,
+                channelId: resolvedMember.channel.id,
+                hasValidBootstrapSession: false,
+              },
+              "Ingress ACL: inactive member bootstrap bypass denied",
+            );
+          }
+        }
+
+        // ── Invite token intercept (inactive member) ──
+        // Same as the non-member branch: invite tokens can reactivate
+        // revoked/pending members without requiring guardian approval.
+        if (inviteToken && denyInactiveMember) {
+          const inviteResult = await handleInviteTokenIntercept({
+            rawToken: inviteToken,
+            sourceChannel,
+            externalChatId: conversationExternalId,
+            externalMessageId,
+            senderExternalUserId: canonicalSenderId ?? rawSenderId,
+            senderName: actorDisplayName,
+            senderUsername: actorUsername,
+            replyCallbackUrl,
+            bearerToken: mintBearerToken(),
+            assistantId,
+            canonicalAssistantId,
+          });
+          if (inviteResult)
+            return {
+              resolvedMember: null,
+              earlyResponse: inviteResult,
+              guardianVerifyCode,
+            };
+        }
+
+        if (denyInactiveMember) {
+          log.info(
+            {
+              sourceChannel,
+              channelId: resolvedMember.channel.id,
+              status: resolvedMember.channel.status,
+            },
+            "Ingress ACL: member not active, denying",
+          );
+
+          // Slack-specific: re-verify inactive members via DM challenge
+          // (same as non-member path). Blocked members are excluded —
+          // the guardian made an explicit decision to block them.
+          if (
+            sourceChannel === "slack" &&
+            resolvedMember.channel.status !== "blocked" &&
+            (canonicalSenderId ?? rawSenderId)
+          ) {
+            const slackVerifyResult = initiateSlackVerificationChallenge({
+              canonicalAssistantId,
+              sourceChannel,
+              conversationExternalId,
+              senderUserId: (canonicalSenderId ?? rawSenderId)!,
+              replyCallbackUrl,
+              mintBearerToken,
+              assistantId,
+            });
+
+            if (slackVerifyResult.initiated) {
+              try {
+                notifyGuardianOfAccessRequest({
+                  canonicalAssistantId,
+                  sourceChannel,
+                  conversationExternalId,
+                  actorExternalId: canonicalSenderId ?? rawSenderId,
+                  actorDisplayName,
+                  actorUsername,
+                  previousMemberStatus: channelStatusToMemberStatus(
+                    resolvedMember.channel.status,
+                  ),
+                });
+              } catch (err) {
+                log.error(
+                  { err, sourceChannel, conversationExternalId },
+                  "Failed to notify guardian of access request (Slack verification, inactive member)",
+                );
+              }
+
+              if (replyCallbackUrl) {
+                try {
+                  await deliverChannelReply(
+                    replyCallbackUrl,
+                    {
+                      chatId: conversationExternalId,
+                      text: "I've notified the owner. They'll share a verification code with you if they approve access.",
+                      assistantId,
+                    },
+                    mintBearerToken(),
+                  );
+                } catch (err) {
+                  log.error(
+                    { err, conversationExternalId },
+                    "Failed to deliver Slack verification prompt reply (inactive member)",
+                  );
+                }
+              }
+
+              return {
+                resolvedMember,
+                earlyResponse: Response.json({
+                  accepted: true,
+                  denied: true,
+                  reason: "verification_challenge_sent",
+                  verificationSessionId: slackVerifyResult.sessionId,
+                }),
+                guardianVerifyCode,
+              };
+            }
+          }
+
+          // For revoked/pending members, notify the guardian so they can
+          // re-approve. Blocked members are intentionally excluded — the
+          // guardian already made an explicit decision to block them.
+          let guardianNotified = false;
+          if (resolvedMember.channel.status !== "blocked") {
+            try {
+              const accessResult = notifyGuardianOfAccessRequest({
+                canonicalAssistantId,
+                sourceChannel,
+                conversationExternalId,
+                actorExternalId: canonicalSenderId ?? rawSenderId,
+                actorDisplayName,
+                actorUsername,
+                previousMemberStatus: channelStatusToMemberStatus(
+                  resolvedMember.channel.status,
+                ),
+              });
+              guardianNotified = accessResult.notified;
+            } catch (err) {
+              log.error(
+                { err, sourceChannel, conversationExternalId },
+                "Failed to notify guardian of access request",
+              );
+            }
+          }
+
+          if (replyCallbackUrl) {
+            const replyText = guardianNotified
+              ? "Hmm looks like you don't have access to talk to me. I'll let them know you tried talking to me and get back to you."
+              : "Sorry, you haven't been approved to message this assistant.";
+            try {
+              await deliverChannelReply(
+                replyCallbackUrl,
+                {
+                  chatId: conversationExternalId,
+                  text: replyText,
+                  assistantId,
+                },
+                mintBearerToken(),
+              );
+            } catch (err) {
+              log.error(
+                { err, conversationExternalId },
+                "Failed to deliver ACL rejection reply",
+              );
+            }
+          }
+          return {
+            resolvedMember,
+            earlyResponse: Response.json({
+              accepted: true,
+              denied: true,
+              reason: `member_${channelStatusToMemberStatus(resolvedMember.channel.status)}`,
+            }),
+            guardianVerifyCode,
+          };
+        }
+      }
+
+      if (resolvedMember.channel.policy === "deny") {
+        log.info(
+          { sourceChannel, channelId: resolvedMember.channel.id },
+          "Ingress ACL: member policy deny",
+        );
+        if (replyCallbackUrl) {
+          try {
+            await deliverChannelReply(
+              replyCallbackUrl,
+              {
+                chatId: conversationExternalId,
+                text: "Sorry, you haven't been approved to message this assistant.",
+                assistantId,
+              },
+              mintBearerToken(),
+            );
+          } catch (err) {
+            log.error(
+              { err, conversationExternalId },
+              "Failed to deliver ACL rejection reply",
+            );
+          }
+        }
+        return {
+          resolvedMember,
+          earlyResponse: Response.json({
+            accepted: true,
+            denied: true,
+            reason: "policy_deny",
+          }),
+          guardianVerifyCode,
+        };
+      }
+
+      // 'allow' or 'escalate' — update last seen and continue
+      touchChannelLastSeen(resolvedMember.channel.id);
+    }
+  }
+
+  return { resolvedMember, guardianVerifyCode };
+}
+
+// ---------------------------------------------------------------------------
+// Invite token intercept
+// ---------------------------------------------------------------------------
+
+/**
+ * Handle an inbound invite token for a non-member or inactive member.
+ *
+ * Redeems the invite, delivers a deterministic reply, and returns a Response
+ * to short-circuit the handler. Returns `null` when the intercept should not
+ * fire (e.g. already_member outcome — let normal flow handle it).
+ */
+async function handleInviteTokenIntercept(params: {
+  rawToken: string;
+  sourceChannel: ChannelId;
+  externalChatId: string;
+  externalMessageId: string;
+  senderExternalUserId?: string;
+  senderName?: string;
+  senderUsername?: string;
+  replyCallbackUrl?: string;
+  bearerToken?: string;
+  assistantId?: string;
+  canonicalAssistantId: string;
+}): Promise<Response | null> {
+  const {
+    rawToken,
+    sourceChannel,
+    externalChatId,
+    externalMessageId,
+    senderExternalUserId,
+    senderName,
+    senderUsername,
+    replyCallbackUrl,
+    bearerToken,
+    assistantId,
+    canonicalAssistantId,
+  } = params;
+
+  // Record the inbound event for dedup tracking BEFORE performing redemption.
+  // Without this, duplicate webhook deliveries (common with Telegram) would
+  // not be tracked: the first delivery redeems the invite and returns early,
+  // then the retry finds an active member, passes ACL, and the raw
+  // /start iv_<token> message leaks into the agent pipeline.
+  const dedupResult = channelDeliveryStore.recordInbound(
+    sourceChannel,
+    externalChatId,
+    externalMessageId,
+    { assistantId: canonicalAssistantId },
+  );
+
+  if (dedupResult.duplicate) {
+    return Response.json({
+      accepted: true,
+      duplicate: true,
+      eventId: dedupResult.eventId,
+    });
+  }
+
+  const outcome = redeemInvite({
+    rawToken,
+    sourceChannel,
+    externalUserId: senderExternalUserId,
+    externalChatId,
+    displayName: senderName,
+    username: senderUsername,
+    assistantId: canonicalAssistantId,
+  });
+
+  log.info(
+    {
+      sourceChannel,
+      externalChatId: params.externalChatId,
+      ok: outcome.ok,
+      type: outcome.ok ? outcome.type : undefined,
+      reason: !outcome.ok ? outcome.reason : undefined,
+    },
+    "Invite token intercept: redemption result",
+  );
+
+  // already_member means the user has an active record — let the normal
+  // flow handle them (they passed ACL or the member is active).
+  if (outcome.ok && outcome.type === "already_member") {
+    // Deliver a quick acknowledgement and short-circuit so the user
+    // does not trigger the deny gate or a duplicate agent loop.
+    const replyText = getInviteRedemptionReply(outcome);
+    if (replyCallbackUrl) {
+      try {
+        await deliverChannelReply(
+          replyCallbackUrl,
+          {
+            chatId: externalChatId,
+            text: replyText,
+            assistantId,
+          },
+          bearerToken,
+        );
+      } catch (err) {
+        log.error(
+          { err, externalChatId },
+          "Failed to deliver invite already-member reply",
+        );
+      }
+    }
+    channelDeliveryStore.markProcessed(dedupResult.eventId);
+    return Response.json({
+      accepted: true,
+      eventId: dedupResult.eventId,
+      inviteRedemption: "already_member",
+    });
+  }
+
+  const replyText = getInviteRedemptionReply(outcome);
+
+  if (replyCallbackUrl) {
+    try {
+      await deliverChannelReply(
+        replyCallbackUrl,
+        {
+          chatId: externalChatId,
+          text: replyText,
+          assistantId,
+        },
+        bearerToken,
+      );
+    } catch (err) {
+      log.error(
+        { err, externalChatId },
+        "Failed to deliver invite redemption reply",
+      );
+    }
+  }
+
+  if (outcome.ok && outcome.type === "redeemed") {
+    channelDeliveryStore.markProcessed(dedupResult.eventId);
+    return Response.json({
+      accepted: true,
+      eventId: dedupResult.eventId,
+      inviteRedemption: "redeemed",
+      memberId: outcome.memberId,
+    });
+  }
+
+  // Failed redemption — inform the user and deny
+  channelDeliveryStore.markProcessed(dedupResult.eventId);
+  return Response.json({
+    accepted: true,
+    eventId: dedupResult.eventId,
+    denied: true,
+    inviteRedemption: outcome.reason,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Slack verification challenge
+// ---------------------------------------------------------------------------
+
+interface SlackVerificationResult {
+  initiated: boolean;
+  sessionId?: string;
+}
+
+/**
+ * Create an outbound verification session for a Slack user. The guardian
+ * receives the verification code via the notification pipeline (not a
+ * direct DM to the requester). The session is identity-bound with
+ * `verificationPurpose: "trusted_contact"` so consuming the code
+ * creates a trusted contact record (not a guardian binding).
+ */
+function initiateSlackVerificationChallenge(params: {
+  canonicalAssistantId: string;
+  sourceChannel: ChannelId;
+  conversationExternalId: string;
+  senderUserId: string;
+  replyCallbackUrl: string | undefined;
+  mintBearerToken: () => string;
+  assistantId: string;
+}): SlackVerificationResult {
+  const { canonicalAssistantId, sourceChannel, senderUserId } = params;
+
+  // Skip if there is already a pending challenge or active session for
+  // this sender to avoid flooding them with duplicate codes. We scope by
+  // sender identity (expectedExternalUserId) so that a pending session for
+  // user A does not suppress challenges for user B.
+  const existingChallenge = getPendingChallenge(
+    canonicalAssistantId,
+    sourceChannel,
+  );
+  const existingSession = findActiveSession(
+    canonicalAssistantId,
+    sourceChannel,
+  );
+  const senderHasPending =
+    (existingChallenge &&
+      existingChallenge.expectedExternalUserId === senderUserId) ||
+    (existingSession &&
+      existingSession.expectedExternalUserId === senderUserId);
+  if (senderHasPending) {
+    log.debug(
+      {
+        sourceChannel,
+        senderUserId,
+        hasChallenge: !!existingChallenge,
+        hasSession: !!existingSession,
+      },
+      "Slack verification: skipping — existing challenge/session for this sender",
+    );
+    return { initiated: false };
+  }
+
+  try {
+    const session = createOutboundSession({
+      assistantId: canonicalAssistantId,
+      channel: sourceChannel,
+      expectedExternalUserId: senderUserId,
+      expectedChatId: senderUserId,
+      identityBindingStatus: "bound",
+      destinationAddress: senderUserId,
+      verificationPurpose: "trusted_contact",
+    });
+
+    // The verification code is delivered to the guardian via the access
+    // request notification flow. The guardian decides whether to share
+    // it with the requester — we do NOT DM the code to the requester.
+
+    log.info(
+      { sourceChannel, senderUserId, sessionId: session.sessionId },
+      "Slack verification challenge initiated for unknown contact",
+    );
+
+    return { initiated: true, sessionId: session.sessionId };
+  } catch (err) {
+    log.error(
+      { err, sourceChannel, senderUserId },
+      "Failed to initiate Slack verification challenge",
+    );
+    return { initiated: false };
+  }
+}