@vellumai/assistant 0.9.0 → 0.10.0-staging.2

package/src/approvals/guardian-request-resolvers.ts

@@ -55,6 +55,87 @@ function shouldUseEphemeral(sourceChannel: string, chatId: string): boolean {
   return sourceChannel === "slack" && chatId.startsWith("C");
 }
 
+/**
+ * Deliver the verification code straight to the requester's Slack DM so the
+ * guardian is never an out-of-band courier for the secret.
+ *
+ * Slack is the only channel with a guaranteed private path to the requester:
+ * posting to their user ID (`U…`) opens a 1:1 DM. The `threadTs` query param is
+ * dropped because it points at the guardian's channel thread and would raise
+ * `thread_not_found` in the DM. The code is sent as a durable (non-ephemeral)
+ * message the requester can refer back to when verifying.
+ *
+ * The verification session is identity-bound to the requester, so delivering
+ * the code to them directly does not widen who can consume it — it only removes
+ * the guardian relay step.
+ *
+ * Returns whether the code was delivered.
+ */
+async function deliverVerificationCodeToSlackRequester(params: {
+  replyCallbackUrl: string;
+  requesterExternalUserId: string;
+  verificationCode: string;
+  assistantId: string;
+}): Promise<boolean> {
+  let callbackUrl = params.replyCallbackUrl;
+  try {
+    const url = new URL(params.replyCallbackUrl);
+    url.searchParams.delete("threadTs");
+    callbackUrl = url.toString();
+  } catch {
+    // Relative path (e.g. the desktop "/deliver/slack" target) — use as-is;
+    // it carries no threadTs to strip.
+  }
+
+  try {
+    await deliverChannelReply(callbackUrl, {
+      chatId: params.requesterExternalUserId,
+      text:
+        "Great news — your access request was approved! " +
+        `Your verification code is: \`${params.verificationCode}\`. ` +
+        "Reply with it here to complete verification. The code expires in 10 minutes.",
+      assistantId: params.assistantId,
+    });
+    return true;
+  } catch (err) {
+    log.error(
+      { err, requesterExternalUserId: params.requesterExternalUserId },
+      "Failed to auto-deliver verification code to Slack requester",
+    );
+    return false;
+  }
+}
+
+/**
+ * Build a requester-facing channel notice (approval/denial/courier text).
+ *
+ * Posts to the originating chat. On a Slack shared channel it goes out as an
+ * ephemeral message visible only to the requester — and because
+ * `chat.postEphemeral` needs a channel ID, `chatId` stays the channel
+ * (`requesterChatId`), never the requester's `U…` user ID.
+ */
+function buildRequesterChannelNotice(params: {
+  channel: string;
+  requesterChatId: string;
+  requesterExternalUserId: string;
+  text: string;
+  assistantId: string;
+}): Parameters<typeof deliverChannelReply>[1] {
+  const payload: Parameters<typeof deliverChannelReply>[1] = {
+    chatId: params.requesterChatId,
+    text: params.text,
+    assistantId: params.assistantId,
+  };
+  if (
+    shouldUseEphemeral(params.channel, params.requesterChatId) &&
+    params.requesterExternalUserId
+  ) {
+    payload.ephemeral = true;
+    payload.user = params.requesterExternalUserId;
+  }
+  return payload;
+}
+
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
@@ -363,8 +444,6 @@ const accessRequestResolver: GuardianRequestResolver = {
     const requesterExternalUserId = request.requesterExternalUserId ?? "";
     const requesterChatId =
       request.requesterChatId ?? request.requesterExternalUserId ?? "";
-    const requesterLabel =
-      requesterExternalUserId || requesterChatId || "the requester";
     const decidedByExternalUserId = ctx.actor.actorExternalUserId ?? "";
     const assistantId = DAEMON_INTERNAL_ASSISTANT_ID;
     const desktopDeliverUrl = resolveDeliverCallbackUrlForChannel(channel);
@@ -373,16 +452,23 @@ const accessRequestResolver: GuardianRequestResolver = {
     const requesterContactResult = requesterExternalUserId
       ? findContactChannel({
           channelType: channel,
-          externalUserId: requesterExternalUserId,
+          address: requesterExternalUserId,
         })
       : null;
     const requesterDisplayName =
       requesterContactResult?.contact.displayName ?? null;
 
+    // Guardian-facing label prefers the contact display name over the raw ID.
+    const requesterLabel =
+      requesterDisplayName ||
+      requesterExternalUserId ||
+      requesterChatId ||
+      "the requester";
+
     const decidedByContactResult = decidedByExternalUserId
       ? findContactChannel({
           channelType: channel,
-          externalUserId: decidedByExternalUserId,
+          address: decidedByExternalUserId,
         })
       : null;
     const decidedByDisplayName =
@@ -397,22 +483,15 @@ const accessRequestResolver: GuardianRequestResolver = {
       // Deliver denial notification and lifecycle signals when channel context is available
       if (channelDeliveryContext) {
         try {
-          const denialPayload: Parameters<typeof deliverChannelReply>[1] = {
-            chatId: requesterChatId,
-            text: "Your access request has been denied.",
-            assistantId,
-          };
-          // On Slack shared channels, deliver as ephemeral so only the requester sees the denial
-          if (
-            shouldUseEphemeral(channel, requesterChatId) &&
-            requesterExternalUserId
-          ) {
-            denialPayload.ephemeral = true;
-            denialPayload.user = requesterExternalUserId;
-          }
           await deliverChannelReply(
             channelDeliveryContext.replyCallbackUrl,
-            denialPayload,
+            buildRequesterChannelNotice({
+              channel,
+              requesterChatId,
+              requesterExternalUserId,
+              text: "Your access request has been denied.",
+              assistantId,
+            }),
           );
         } catch (err) {
           log.error(
@@ -563,7 +642,7 @@ const accessRequestResolver: GuardianRequestResolver = {
 
       // Deliver verification code to guardian
       const codeText =
-        `You approved access for ${requesterExternalUserId}. ` +
+        `You approved access for ${requesterLabel}. ` +
         `Give them this verification code: \`${session.secret}\`. ` +
         `The code expires in 10 minutes.`;
       try {
@@ -629,12 +708,8 @@ const accessRequestResolver: GuardianRequestResolver = {
         }
       }
 
-      // Notify the requester. For Slack, route to DM via the user ID and
-      // strip threadTs (which belongs to the guardian's channel thread).
-      const requesterTargetChatId =
-        channel === "slack" && requesterExternalUserId
-          ? requesterExternalUserId
-          : requesterChatId;
+      // Strip threadTs from the requester reply URL — it belongs to the
+      // guardian's channel thread and would cause thread_not_found in a DM.
       let requesterCallbackUrl = channelDeliveryContext.replyCallbackUrl;
       if (channel === "slack" && requesterExternalUserId) {
         try {
@@ -647,47 +722,58 @@ const accessRequestResolver: GuardianRequestResolver = {
       }
 
       if (codeDelivered) {
-        try {
-          const approvalPayload: Parameters<typeof deliverChannelReply>[1] = {
-            chatId: requesterTargetChatId,
-            text:
-              "Your access request has been approved! " +
-              "Please enter the 6-digit verification code you receive from the guardian.",
-            assistantId,
-          };
-          // On Slack shared channels, deliver as ephemeral so only the requester sees
-          if (
-            shouldUseEphemeral(channel, requesterChatId) &&
-            requesterExternalUserId
-          ) {
-            approvalPayload.ephemeral = true;
-            approvalPayload.user = requesterExternalUserId;
-          }
-          await deliverChannelReply(requesterCallbackUrl, approvalPayload);
+        // On Slack, deliver the code straight to the requester's DM so the
+        // guardian doesn't have to relay it. Other channels (and a failed Slack
+        // delivery) fall back to the courier notice — there is no guaranteed
+        // private path to the requester elsewhere (e.g. group chats).
+        const requesterCodeDelivered =
+          channel === "slack" && requesterExternalUserId
+            ? await deliverVerificationCodeToSlackRequester({
+                replyCallbackUrl: channelDeliveryContext.replyCallbackUrl,
+                requesterExternalUserId,
+                verificationCode: session.secret,
+                assistantId,
+              })
+            : false;
+
+        if (requesterCodeDelivered) {
           requesterNotified = true;
-        } catch (err) {
-          log.error(
-            { err, requesterChatId },
-            "Failed to notify requester of access request approval",
-          );
+        } else {
+          try {
+            await deliverChannelReply(
+              requesterCallbackUrl,
+              buildRequesterChannelNotice({
+                channel,
+                requesterChatId,
+                requesterExternalUserId,
+                text:
+                  "Your access request has been approved! " +
+                  "Please enter the 6-digit verification code you receive from the guardian.",
+                assistantId,
+              }),
+            );
+            requesterNotified = true;
+          } catch (err) {
+            log.error(
+              { err, requesterChatId },
+              "Failed to notify requester of access request approval",
+            );
+          }
         }
       } else {
         try {
-          const failurePayload: Parameters<typeof deliverChannelReply>[1] = {
-            chatId: requesterTargetChatId,
-            text:
-              "Your access request was approved, but we were unable to " +
-              "deliver the verification code. Please try again later.",
-            assistantId,
-          };
-          if (
-            shouldUseEphemeral(channel, requesterChatId) &&
-            requesterExternalUserId
-          ) {
-            failurePayload.ephemeral = true;
-            failurePayload.user = requesterExternalUserId;
-          }
-          await deliverChannelReply(requesterCallbackUrl, failurePayload);
+          await deliverChannelReply(
+            requesterCallbackUrl,
+            buildRequesterChannelNotice({
+              channel,
+              requesterChatId,
+              requesterExternalUserId,
+              text:
+                "Your access request was approved, but we were unable to " +
+                "deliver the verification code. Please try again later.",
+              assistantId,
+            }),
+          );
         } catch (err) {
           log.error(
             { err, requesterChatId },
@@ -721,26 +807,43 @@ const accessRequestResolver: GuardianRequestResolver = {
         });
       }
     } else if (desktopDeliverUrl && requesterChatId) {
-      // For Slack, route to DM via requesterExternalUserId (user ID) instead
-      // of requesterChatId (channel ID) to avoid posting in public channels.
-      const targetChatId =
+      // Guardian decided off-channel (e.g. desktop) but the requester is on a
+      // deliverable channel. On Slack, DM the code directly (parity with the
+      // on-channel path); otherwise fall back to the courier notice.
+      const requesterCodeDelivered =
         channel === "slack" && requesterExternalUserId
-          ? requesterExternalUserId
-          : requesterChatId;
-      try {
-        await deliverChannelReply(desktopDeliverUrl, {
-          chatId: targetChatId,
-          text:
-            "Your access request has been approved! " +
-            "Please enter the 6-digit verification code you receive from the guardian.",
-          assistantId,
-        });
+          ? await deliverVerificationCodeToSlackRequester({
+              replyCallbackUrl: desktopDeliverUrl,
+              requesterExternalUserId,
+              verificationCode: session.secret,
+              assistantId,
+            })
+          : false;
+
+      if (requesterCodeDelivered) {
         requesterNotified = true;
-      } catch (err) {
-        log.error(
-          { err, requesterChatId },
-          "Failed to notify requester of access request approval (desktop decision path)",
-        );
+      } else {
+        // For Slack, route to DM via requesterExternalUserId (user ID) instead
+        // of requesterChatId (channel ID) to avoid posting in public channels.
+        const targetChatId =
+          channel === "slack" && requesterExternalUserId
+            ? requesterExternalUserId
+            : requesterChatId;
+        try {
+          await deliverChannelReply(desktopDeliverUrl, {
+            chatId: targetChatId,
+            text:
+              "Your access request has been approved! " +
+              "Please enter the 6-digit verification code you receive from the guardian.",
+            assistantId,
+          });
+          requesterNotified = true;
+        } catch (err) {
+          log.error(
+            { err, requesterChatId },
+            "Failed to notify requester of access request approval (desktop decision path)",
+          );
+        }
       }
     }
 

package/src/calls/__tests__/channel-admission-reader.test.ts

@@ -0,0 +1,132 @@
+/**
+ * Tests for the gateway-backed channel admission policy reader.
+ *
+ * The reader fails open (returns null = admit) so a gateway IPC failure can
+ * never block a live call. These tests pin that contract plus the TTL cache.
+ */
+
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+// ── Controllable IPC mock ────────────────────────────────────────────────────
+
+type IpcHandler = (params?: Record<string, unknown>) => unknown;
+
+const ipcHandlers = new Map<string, IpcHandler>();
+const ipcCallLog: Array<{
+  method: string;
+  params?: Record<string, unknown>;
+  timeoutMs?: number;
+}> = [];
+
+mock.module("../../ipc/gateway-client.js", () => ({
+  ipcCall: async (
+    method: string,
+    params?: Record<string, unknown>,
+    timeoutMs?: number,
+  ) => {
+    ipcCallLog.push({ method, params, timeoutMs });
+    const handler = ipcHandlers.get(method);
+    return handler ? handler(params) : undefined;
+  },
+  ipcCallPersistent: async () => undefined,
+  resetPersistentClient: () => {},
+}));
+
+import {
+  _clearCacheForTesting,
+  getChannelAdmissionPolicy,
+} from "../channel-admission-reader.js";
+
+const METHOD = "get_channel_admission_policy";
+
+function countCalls(method: string): number {
+  return ipcCallLog.filter((c) => c.method === method).length;
+}
+
+describe("getChannelAdmissionPolicy", () => {
+  beforeEach(() => {
+    _clearCacheForTesting();
+    ipcHandlers.clear();
+    ipcCallLog.length = 0;
+  });
+
+  test("returns the gateway-resolved policy and caches it within the TTL", async () => {
+    ipcHandlers.set(METHOD, () => ({ policy: "guardian_only" }));
+
+    expect(await getChannelAdmissionPolicy("telegram")).toBe("guardian_only");
+    // Second call within TTL is served from cache — no extra IPC round-trip.
+    expect(await getChannelAdmissionPolicy("telegram")).toBe("guardian_only");
+    expect(countCalls(METHOD)).toBe(1);
+  });
+
+  test("bounds the IPC read with a short timeout so it fails open promptly", async () => {
+    ipcHandlers.set(METHOD, () => ({ policy: "guardian_only" }));
+
+    await getChannelAdmissionPolicy("telegram");
+
+    const call = ipcCallLog.find((c) => c.method === METHOD);
+    expect(call?.timeoutMs).toBe(1_000);
+  });
+
+  test("returns null when IPC transport fails (undefined)", async () => {
+    ipcHandlers.set(METHOD, () => undefined);
+    expect(await getChannelAdmissionPolicy("telegram")).toBeNull();
+  });
+
+  test("returns null when the gateway explicitly resolves no policy", async () => {
+    ipcHandlers.set(METHOD, () => ({ policy: null }));
+    expect(await getChannelAdmissionPolicy("telegram")).toBeNull();
+  });
+
+  test("returns null when the IPC call throws", async () => {
+    ipcHandlers.set(METHOD, () => {
+      throw new Error("socket exploded");
+    });
+    expect(await getChannelAdmissionPolicy("telegram")).toBeNull();
+  });
+
+  test("returns null for an invalid policy string", async () => {
+    ipcHandlers.set(METHOD, () => ({ policy: "definitely-not-a-policy" }));
+    expect(await getChannelAdmissionPolicy("telegram")).toBeNull();
+  });
+
+  test("caches the explicit no-enforcement (null) answer within the TTL", async () => {
+    // The gateway successfully said "no enforcement" — a real, cacheable answer.
+    ipcHandlers.set(METHOD, () => ({ policy: null }));
+    expect(await getChannelAdmissionPolicy("telegram")).toBeNull();
+    expect(await getChannelAdmissionPolicy("telegram")).toBeNull();
+    expect(countCalls(METHOD)).toBe(1);
+  });
+
+  test("does NOT cache a transport failure (undefined) — re-consults the gateway", async () => {
+    // First setup: gateway hiccup → fail open to null, NOT cached.
+    ipcHandlers.set(METHOD, () => undefined);
+    expect(await getChannelAdmissionPolicy("telegram")).toBeNull();
+
+    // Gateway recovers with a restrictive policy: the next setup must re-attempt
+    // the IPC (not serve a stale fail-open null) and honor the now-recovered floor.
+    ipcHandlers.set(METHOD, () => ({ policy: "guardian_only" }));
+    expect(await getChannelAdmissionPolicy("telegram")).toBe("guardian_only");
+    expect(countCalls(METHOD)).toBe(2);
+  });
+
+  test("does NOT cache a thrown IPC error — re-consults the gateway", async () => {
+    ipcHandlers.set(METHOD, () => {
+      throw new Error("socket exploded");
+    });
+    expect(await getChannelAdmissionPolicy("telegram")).toBeNull();
+
+    ipcHandlers.set(METHOD, () => ({ policy: "no_one" }));
+    expect(await getChannelAdmissionPolicy("telegram")).toBe("no_one");
+    expect(countCalls(METHOD)).toBe(2);
+  });
+
+  test("does NOT cache a malformed shape — re-consults the gateway", async () => {
+    ipcHandlers.set(METHOD, () => ({ policy: "definitely-not-a-policy" }));
+    expect(await getChannelAdmissionPolicy("telegram")).toBeNull();
+
+    ipcHandlers.set(METHOD, () => ({ policy: "guardian_only" }));
+    expect(await getChannelAdmissionPolicy("telegram")).toBe("guardian_only");
+    expect(countCalls(METHOD)).toBe(2);
+  });
+});