switchroom 0.10.0 → 0.11.1

package/telegram-plugin/gateway/drive-write-approval.ts

@@ -0,0 +1,243 @@
+/**
+ * Drive-write approval handler — RFC E §4.2 Cut 2.
+ *
+ * Called by the gateway's IPC dispatcher when the Drive-write
+ * PreToolUse hook sends a `request_drive_approval` message. The
+ * handler:
+ *
+ *   1. Validates the inbound preview payload via `buildDiffPreview`
+ *      (which fails closed on malformed inputs).
+ *   2. Registers a kernel approval request at scope
+ *      `doc:gdrive:write:<fileId>`, action `write`, approver_set =
+ *      operator allowFrom.
+ *   3. Builds the Telegram card via `buildDiffPreviewCard` (#1299).
+ *   4. Posts the card to the operator chat via grammy.
+ *   5. Sends a `drive_approval_posted` event back over IPC with the
+ *      kernel request_id + expires_at so the hook can poll
+ *      `approval_lookup` for the verdict.
+ *
+ * On any failure the handler sends `drive_approval_posted { ok:
+ * false, reason: ... }` so the hook fails closed (blocks the tool).
+ *
+ * Kept in its own module so the unit tests for the orchestration
+ * (kernel call + card build + post + response) live separately
+ * from the gateway monolith.
+ */
+
+import { buildDiffPreview, type DiffPreviewInput } from "../../src/drive/diff-preview.js";
+import type { IpcClient } from "./ipc-server.js";
+import type {
+  DriveApprovalPostedEvent,
+  RequestDriveApprovalMessage,
+} from "./ipc-protocol.js";
+
+// ────────────────────────────────────────────────────────────────────────
+// Injected deps — caller (gateway.ts) wires these from the existing
+// surface area. Kept abstract so the handler unit-tests don't need
+// grammy / the kernel / the gateway in scope.
+// ────────────────────────────────────────────────────────────────────────
+
+export interface DriveApprovalHandlerDeps {
+  /** This gateway's agent name — cross-agent requests rejected. */
+  agentName: string;
+  /**
+   * Operator allowFrom list (Telegram user ids as strings) — used
+   * as the kernel's approver_set, and to pick the target chat for
+   * the card post.
+   */
+  loadAllowFrom: () => string[];
+  /**
+   * The chat (and optional topic) the picker card should land in.
+   * For the standard DM-based operator setup this is the operator's
+   * private chat with the bot; for group-based setups the operator
+   * group chat + the agent's topic id.
+   */
+  loadTargetChat: () => {
+    chatId: number | string;
+    threadId?: number;
+  } | null;
+  /**
+   * Register a kernel approval request. Returns the kernel's
+   * request_id + expires_at_ms on success, null on failure (rate
+   * limit, broker unreachable, etc.).
+   */
+  registerApproval: (args: {
+    agent_unit: string;
+    scope: string;
+    action: string;
+    approver_set: string[];
+    why: string;
+    ttl_ms: number;
+  }) => Promise<{ request_id: string; expires_at_ms: number } | null>;
+  /**
+   * Post the diff-preview card to Telegram. Returns a posted
+   * message id on success, null on failure.
+   */
+  postCard: (args: {
+    chatId: number | string;
+    threadId?: number;
+    text: string;
+    /** grammy's InlineKeyboard, passed straight through. */
+    replyMarkup: unknown;
+  }) => Promise<{ messageId: number } | null>;
+  /**
+   * Build the Telegram-shaped card from a DiffPreview. Pass-through
+   * to `buildDiffPreviewCard` (#1299); deferred via deps so the
+   * handler tests don't need grammy.
+   */
+  buildCard: (args: {
+    preview: ReturnType<typeof buildDiffPreview>;
+    suggestRequestId: string;
+  }) => { text: string; reply_markup: unknown };
+  log?: (msg: string) => void;
+  /** TTL clamping policy. */
+  defaultTtlMs?: number;
+  maxTtlMs?: number;
+  minTtlMs?: number;
+}
+
+const DEFAULT_TTL_MS = 5 * 60 * 1000; // 5 minutes
+const MAX_TTL_MS = 30 * 60 * 1000; // 30 minutes
+const MIN_TTL_MS = 30 * 1000; // 30 seconds
+
+/**
+ * Top-level handler called by ipc-server's onRequestDriveApproval.
+ * Always sends a single `drive_approval_posted` reply (success or
+ * failure) before returning.
+ */
+export async function handleRequestDriveApproval(
+  client: Pick<IpcClient, "send">,
+  msg: RequestDriveApprovalMessage,
+  deps: DriveApprovalHandlerDeps,
+): Promise<void> {
+  const reply = (event: Omit<DriveApprovalPostedEvent, "type">) => {
+    try {
+      client.send({ type: "drive_approval_posted", ...event });
+    } catch (err) {
+      deps.log?.(
+        `drive_approval_posted send failed (correlation=${msg.correlationId}): ${(err as Error).message}`,
+      );
+    }
+  };
+
+  // 1. Cross-agent guard.
+  if (msg.agentName !== deps.agentName) {
+    reply({
+      correlationId: msg.correlationId,
+      ok: false,
+      reason: `gateway serves '${deps.agentName}', not '${msg.agentName}'`,
+    });
+    return;
+  }
+
+  // 2. Validate preview shape — buildDiffPreview throws on
+  // malformed inputs (fileId missing, metrics invalid, etc).
+  let preview: ReturnType<typeof buildDiffPreview>;
+  try {
+    preview = buildDiffPreview(msg.preview as unknown as DiffPreviewInput);
+  } catch (err) {
+    reply({
+      correlationId: msg.correlationId,
+      ok: false,
+      reason: `invalid preview payload: ${(err as Error).message}`,
+    });
+    return;
+  }
+
+  // 3. Pull operator targeting + allowFrom.
+  const allowFrom = deps.loadAllowFrom();
+  if (allowFrom.length === 0) {
+    reply({
+      correlationId: msg.correlationId,
+      ok: false,
+      reason: "no operator allowFrom configured — cannot route approval",
+    });
+    return;
+  }
+  const target = deps.loadTargetChat();
+  if (target === null) {
+    reply({
+      correlationId: msg.correlationId,
+      ok: false,
+      reason: "no target chat available — operator not paired?",
+    });
+    return;
+  }
+
+  // 4. TTL clamp.
+  const ttlMs = clampTtl(
+    msg.ttlMs,
+    deps.defaultTtlMs ?? DEFAULT_TTL_MS,
+    deps.minTtlMs ?? MIN_TTL_MS,
+    deps.maxTtlMs ?? MAX_TTL_MS,
+  );
+
+  // 5. Kernel approval request.
+  const fileId = preview.audit.wrapperAttested.fileId;
+  const scope = `doc:gdrive:write:${fileId}`;
+  const registered = await deps.registerApproval({
+    agent_unit: deps.agentName,
+    scope,
+    action: "write",
+    approver_set: allowFrom,
+    why: `Drive write — ${preview.audit.wrapperAttested.docTitle}`,
+    ttl_ms: ttlMs,
+  });
+  if (registered === null) {
+    reply({
+      correlationId: msg.correlationId,
+      ok: false,
+      reason: "kernel approval_request failed (rate limit or broker unreachable)",
+    });
+    return;
+  }
+
+  // 6. Build + post the card.
+  let card: { text: string; reply_markup: unknown };
+  try {
+    card = deps.buildCard({ preview, suggestRequestId: registered.request_id });
+  } catch (err) {
+    reply({
+      correlationId: msg.correlationId,
+      ok: false,
+      reason: `card build failed: ${(err as Error).message}`,
+    });
+    return;
+  }
+  const posted = await deps.postCard({
+    chatId: target.chatId,
+    ...(target.threadId !== undefined ? { threadId: target.threadId } : {}),
+    text: card.text,
+    replyMarkup: card.reply_markup,
+  });
+  if (posted === null) {
+    reply({
+      correlationId: msg.correlationId,
+      ok: false,
+      reason: "Telegram sendMessage failed",
+    });
+    return;
+  }
+
+  deps.log?.(
+    `drive_approval_posted ok correlation=${msg.correlationId} request_id=${registered.request_id} file=${fileId}`,
+  );
+  reply({
+    correlationId: msg.correlationId,
+    ok: true,
+    requestId: registered.request_id,
+    expiresAtMs: registered.expires_at_ms,
+  });
+}
+
+function clampTtl(
+  requested: number | undefined,
+  fallback: number,
+  min: number,
+  max: number,
+): number {
+  const t = requested === undefined || !Number.isFinite(requested) ? fallback : requested;
+  if (t < min) return min;
+  if (t > max) return max;
+  return t;
+}

package/telegram-plugin/gateway/folder-picker-handler.test.ts

@@ -0,0 +1,314 @@
+/**
+ * Tests for folder-picker Telegram handlers — RFC E §4.1 wire-up.
+ *
+ * The handlers are kernel/Drive/grammy-agnostic via injected deps;
+ * tests use minimal stub contexts + fake deps.
+ */
+
+import { describe, expect, it } from "vitest";
+import type { Context } from "grammy";
+
+import { FolderListCache } from "../../src/drive/folder-list.js";
+import type { FolderPage } from "../../src/drive/folder-list.js";
+import {
+  handleFolderPickerCallback,
+  handleFoldersCommand,
+  type FolderPickerHandlerDeps,
+} from "./folder-picker-handler.js";
+
+interface FakeCtx {
+  from: { id: number };
+  replies: Array<{ text: string; keyboardRows: string[][] }>;
+  edits: Array<{ text: string; keyboardRows: string[][] | undefined }>;
+  callbackAnswers: Array<{ text?: string }>;
+}
+
+function fakeCtx(userId = 12345): { ctx: Context; spy: FakeCtx } {
+  const spy: FakeCtx = {
+    from: { id: userId },
+    replies: [],
+    edits: [],
+    callbackAnswers: [],
+  };
+  const ctx = {
+    from: spy.from,
+    reply: async (text: string, opts?: { reply_markup?: { inline_keyboard?: unknown[][] } }) => {
+      const rows = (opts?.reply_markup?.inline_keyboard ?? []) as Array<
+        Array<{ text: string }>
+      >;
+      spy.replies.push({
+        text,
+        keyboardRows: rows.map((r) => r.map((b) => b.text)),
+      });
+      return { message_id: 1 };
+    },
+    editMessageText: async (text: string, opts?: { reply_markup?: { inline_keyboard?: unknown[][] } }) => {
+      const rows = (opts?.reply_markup?.inline_keyboard ?? []) as Array<
+        Array<{ text: string }>
+      >;
+      spy.edits.push({
+        text,
+        keyboardRows: opts?.reply_markup
+          ? rows.map((r) => r.map((b) => b.text))
+          : undefined,
+      });
+      return true;
+    },
+    answerCallbackQuery: async (arg?: { text?: string }) => {
+      spy.callbackAnswers.push(arg ?? {});
+      return true;
+    },
+  } as unknown as Context;
+  return { ctx, spy };
+}
+
+interface FakeKernel {
+  requests: Array<{ scope: string; action: string }>;
+  consumed: string[];
+  recorded: Array<{
+    request_id: string;
+    decision: string;
+    approver_set: string[];
+  }>;
+  nextRequestId: string;
+  failRequest?: boolean;
+  failConsume?: boolean;
+  failRecord?: boolean;
+}
+
+function depsFor(args: {
+  agentName?: string;
+  fetchPage?: FolderPickerHandlerDeps["fetchPage"];
+  cache?: FolderListCache;
+  kernel?: FakeKernel;
+}): { deps: FolderPickerHandlerDeps; kernel: FakeKernel; cache: FolderListCache } {
+  const cache = args.cache ?? new FolderListCache({ now: () => 1000 });
+  const kernel: FakeKernel = args.kernel ?? {
+    requests: [],
+    consumed: [],
+    recorded: [],
+    nextRequestId: "abcdef01",
+  };
+  const deps: FolderPickerHandlerDeps = {
+    agentName: args.agentName ?? "klanker",
+    cache,
+    fetchPage:
+      args.fetchPage ??
+      (async () => ({ folders: [{ id: "F1", name: "Work" }] })),
+    approvalRequest: async (a) => {
+      if (kernel.failRequest) return null;
+      kernel.requests.push({ scope: a.scope, action: a.action });
+      return { request_id: kernel.nextRequestId };
+    },
+    approvalConsume: async (id) => {
+      if (kernel.failConsume) return false;
+      kernel.consumed.push(id);
+      return true;
+    },
+    approvalRecord: async (a) => {
+      if (kernel.failRecord) return null;
+      kernel.recorded.push({
+        request_id: a.request_id,
+        decision: a.decision,
+        approver_set: a.approver_set,
+      });
+      return "dec-1";
+    },
+  };
+  return { deps, kernel, cache };
+}
+
+describe("handleFoldersCommand", () => {
+  it("posts a picker card with the top-level folders", async () => {
+    const { ctx, spy } = fakeCtx();
+    const { deps } = depsFor({});
+    await handleFoldersCommand(ctx, deps);
+    expect(spy.replies).toHaveLength(1);
+    expect(spy.replies[0]?.text).toContain("📁");
+    expect(spy.replies[0]?.text).toContain("1 folder");
+    // Two folder rows ([Allow] + [Browse]) plus nav row.
+    expect(spy.replies[0]?.keyboardRows.length).toBeGreaterThanOrEqual(3);
+  });
+
+  it("hits the cache on a re-issued /folders within TTL", async () => {
+    const { ctx, spy } = fakeCtx();
+    let fetches = 0;
+    const { deps } = depsFor({
+      fetchPage: async () => {
+        fetches += 1;
+        return { folders: [{ id: "F1", name: "Work" }] };
+      },
+    });
+    await handleFoldersCommand(ctx, deps);
+    await handleFoldersCommand(ctx, deps);
+    expect(fetches).toBe(1);
+    expect(spy.replies).toHaveLength(2);
+  });
+
+  it("surfaces a Drive failure as a friendly error message (no crash)", async () => {
+    const { ctx, spy } = fakeCtx();
+    const { deps } = depsFor({
+      fetchPage: async () => {
+        throw new Error("HTTP 401");
+      },
+    });
+    await handleFoldersCommand(ctx, deps);
+    expect(spy.replies[0]?.text).toContain("Drive folder listing failed");
+    expect(spy.replies[0]?.text).toContain("HTTP 401");
+  });
+});
+
+describe("handleFolderPickerCallback — refusal cases", () => {
+  it("rejects a malformed callback", async () => {
+    const { ctx, spy } = fakeCtx();
+    const { deps } = depsFor({});
+    await handleFolderPickerCallback(ctx, "not-a-drvpick-callback", deps);
+    expect(spy.callbackAnswers[0]?.text).toMatch(/malformed/);
+    expect(spy.edits).toEqual([]);
+  });
+
+  it("refuses callbacks for a different agent (path-scoped guard)", async () => {
+    const { ctx, spy } = fakeCtx();
+    const { deps } = depsFor({ agentName: "klanker" });
+    await handleFolderPickerCallback(ctx, "drvpick:grant:clerk:F1", deps);
+    expect(spy.callbackAnswers[0]?.text).toMatch(/this gateway serves 'klanker'/);
+    expect(spy.edits).toEqual([]);
+  });
+});
+
+describe("handleFolderPickerCallback — navigation", () => {
+  it("enter drills into a sub-folder (cache miss → fetchPage with parent_id)", async () => {
+    const { ctx, spy } = fakeCtx();
+    const fetched: string[] = [];
+    const { deps } = depsFor({
+      fetchPage: async ({ parent_id }) => {
+        fetched.push(parent_id ?? "<top>");
+        return { folders: [{ id: "SUB1", name: "Q3" }] };
+      },
+    });
+    await handleFolderPickerCallback(ctx, "drvpick:enter:klanker:F1", deps);
+    expect(fetched).toEqual(["F1"]);
+    expect(spy.edits[0]?.text).toContain("/F1");
+    expect(spy.callbackAnswers[0]).toEqual({});
+  });
+
+  it("back returns to the named parent level", async () => {
+    const { ctx, spy } = fakeCtx();
+    const fetched: string[] = [];
+    const { deps } = depsFor({
+      fetchPage: async ({ parent_id }) => {
+        fetched.push(parent_id ?? "<top>");
+        return { folders: [] };
+      },
+    });
+    await handleFolderPickerCallback(ctx, "drvpick:back:klanker:PARENT1", deps);
+    expect(fetched).toEqual(["PARENT1"]);
+  });
+
+  it("back to top-of-Drive (empty parent_id) fetches the top page", async () => {
+    const { ctx, spy } = fakeCtx();
+    const fetched: Array<string | undefined> = [];
+    const { deps } = depsFor({
+      fetchPage: async ({ parent_id }) => {
+        fetched.push(parent_id);
+        return { folders: [] };
+      },
+    });
+    await handleFolderPickerCallback(ctx, "drvpick:back:klanker:", deps);
+    expect(fetched).toEqual([undefined]);
+  });
+
+  it("refresh bypasses cache (forceRefresh)", async () => {
+    const cache = new FolderListCache({ now: () => 1000 });
+    cache.set("klanker", { folders: [{ id: "STALE", name: "S" }] });
+    let fetches = 0;
+    const { ctx, spy } = fakeCtx();
+    const { deps } = depsFor({
+      cache,
+      fetchPage: async () => {
+        fetches += 1;
+        return { folders: [{ id: "FRESH", name: "F" }] };
+      },
+    });
+    await handleFolderPickerCallback(ctx, "drvpick:refresh:klanker:", deps);
+    expect(fetches).toBe(1);
+    expect(spy.edits[0]?.text).toContain("📁");
+  });
+
+  it("open resolves a page-token handle back to the real Drive token", async () => {
+    const cache = new FolderListCache({ now: () => 1000 });
+    const handle = cache.registerPageToken("klanker", "REAL_DRIVE_TOKEN_120_CHARS_XXXXXX");
+    const { ctx, spy } = fakeCtx();
+    let observedToken: string | undefined;
+    const { deps } = depsFor({
+      cache,
+      fetchPage: async ({ page_token }) => {
+        observedToken = page_token;
+        return { folders: [{ id: "F2", name: "Page 2" }] };
+      },
+    });
+    await handleFolderPickerCallback(
+      ctx,
+      `drvpick:open:klanker::${handle}`,
+      deps,
+    );
+    expect(observedToken).toBe("REAL_DRIVE_TOKEN_120_CHARS_XXXXXX");
+    // The folder name lands in the [Allow / Browse] keyboard rows,
+    // not the body line.
+    const flat = spy.edits[0]?.keyboardRows.flat() ?? [];
+    expect(flat.some((b) => b.includes("Page 2"))).toBe(true);
+  });
+});
+
+describe("handleFolderPickerCallback — grant", () => {
+  it("records the grant via the three-step kernel call and confirms in-place", async () => {
+    const { ctx, spy } = fakeCtx(99999);
+    const { deps, kernel } = depsFor({});
+    await handleFolderPickerCallback(ctx, "drvpick:grant:klanker:F1", deps);
+    expect(kernel.requests).toEqual([
+      { scope: "doc:gdrive:folder/F1/**", action: "read" },
+    ]);
+    expect(kernel.consumed).toEqual(["abcdef01"]);
+    expect(kernel.recorded).toEqual([
+      {
+        request_id: "abcdef01",
+        decision: "allow_always",
+        approver_set: ["99999"],
+      },
+    ]);
+    expect(spy.edits[0]?.text).toContain("✅ Granted klanker");
+    expect(spy.edits[0]?.text).toContain("doc:gdrive:folder/F1/**");
+    expect(spy.edits[0]?.text).toContain("/approvals revoke dec-1");
+    // Confirmation keyboard has Open-in-Drive URL.
+    expect(spy.edits[0]?.keyboardRows[0]).toEqual(["📖 Open in Drive"]);
+    expect(spy.callbackAnswers[0]?.text).toBe("Allowed");
+  });
+
+  it("surfaces each kernel failure step with a clear toast", async () => {
+    for (const failure of [
+      { failRequest: true, msg: /request failed/ },
+      { failConsume: true, msg: /consume failed/ },
+      { failRecord: true, msg: /record failed/ },
+    ] as const) {
+      const { ctx, spy } = fakeCtx();
+      const kernel: FakeKernel = {
+        requests: [],
+        consumed: [],
+        recorded: [],
+        nextRequestId: "abcdef01",
+        ...failure,
+      };
+      const { deps } = depsFor({ kernel });
+      await handleFolderPickerCallback(ctx, "drvpick:grant:klanker:F1", deps);
+      expect(spy.callbackAnswers[0]?.text).toMatch(failure.msg);
+      expect(spy.edits).toEqual([]); // no confirmation edit on failure
+    }
+  });
+
+  it("refuses when ctx.from is missing (no user id)", async () => {
+    const { ctx, spy } = fakeCtx(0);
+    const { deps } = depsFor({});
+    await handleFolderPickerCallback(ctx, "drvpick:grant:klanker:F1", deps);
+    expect(spy.callbackAnswers[0]?.text).toMatch(/user id/);
+  });
+});