@vellumai/vellum-gateway 0.7.3 → 0.8.1

package/src/__tests__/ipc-route-policy-coverage.test.ts

@@ -0,0 +1,297 @@
+/**
+ * Lint test: every daemon route whose HTTP-side policy is gateway-only
+ * MUST have a matching IPC policy entry, with matching required scopes.
+ *
+ * Background: the gateway's IPC proxy default-allows operationIds that
+ * have no policy entry. Routes restricted to the `svc_gateway` principal
+ * on the daemon HTTP path must also be locked down on IPC — otherwise an
+ * authenticated edge JWT can reach them by setting
+ * `X-Vellum-Proxy-Server: ipc`, bypassing the daemon HTTP router entirely.
+ *
+ * Symmetrically, the IPC entry's `requiredScopes` must match the daemon's
+ * `requiredScopes`. If IPC permits a broader scope than the daemon HTTP
+ * path requires, the IPC path is more permissive than the HTTP path —
+ * the same scope-bypass class this guard is designed to prevent.
+ *
+ * This bug class has bitten us multiple times:
+ *   - PR #29571 (MCP OAuth routes — Codex finding)
+ *   - PR #29612 (OAuth connect routes — Codex finding)
+ *
+ * Rather than rely on Codex catching it a third time, this test walks
+ * the daemon route source files and the daemon route-policy source file
+ * at test time and asserts every gateway-only operationId is registered
+ * in the IPC policy table with matching scopes and principals.
+ *
+ * Implementation notes:
+ *   - Uses text parsing rather than direct imports because the gateway
+ *     and assistant packages don't share source-level imports (they
+ *     communicate through the `@vellumai/service-contracts` package).
+ *   - Regexes are intentionally loose. False positives (matching too
+ *     much) only result in extra coverage; false negatives (missing
+ *     real gateway-only routes) defeat the lint.
+ *   - Daemon route endpoints may include parameter segments
+ *     (e.g. `internal/oauth/connect/status/:state`) while the
+ *     daemon's route-policy keys drop those segments
+ *     (e.g. `internal/oauth/connect/status`). We normalize by
+ *     stripping `/:param` segments before matching so parameterized
+ *     gateway-only routes are not silently excluded.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { getIpcRoutePolicy } from "../auth/ipc-route-policy.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// gateway/src/__tests__ → repo root → assistant/...
+const ASSISTANT_SRC = join(
+  __dirname,
+  "..",
+  "..",
+  "..",
+  "assistant",
+  "src",
+);
+const ROUTES_DIR = join(ASSISTANT_SRC, "runtime", "routes");
+const ROUTE_POLICY_FILE = join(
+  ASSISTANT_SRC,
+  "runtime",
+  "auth",
+  "route-policy.ts",
+);
+
+// ---------------------------------------------------------------------------
+// Step 1 — Collect every (operationId, endpoint) pair from daemon routes.
+// ---------------------------------------------------------------------------
+
+interface RoutePair {
+  operationId: string;
+  endpoint: string;
+  sourceFile: string;
+}
+
+function collectRouteSourceFiles(dir: string): string[] {
+  const out: string[] = [];
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    const st = statSync(full);
+    if (st.isDirectory()) {
+      if (entry === "__tests__") continue;
+      out.push(...collectRouteSourceFiles(full));
+      continue;
+    }
+    if (!entry.endsWith(".ts")) continue;
+    if (entry.endsWith(".test.ts")) continue;
+    out.push(full);
+  }
+  return out;
+}
+
+/**
+ * For each `operationId: "..."` literal, find the closest `endpoint: "..."`
+ * literal within a 600-character window. The codebase's style writes both
+ * fields near the top of each route definition, so 600 chars comfortably
+ * covers the longest route block.
+ */
+function extractRoutePairs(source: string, sourceFile: string): RoutePair[] {
+  const pairs: RoutePair[] = [];
+  const opRegex = /operationId:\s*["']([^"']+)["']/g;
+  for (const m of source.matchAll(opRegex)) {
+    const operationId = m[1]!;
+    const start = m.index!;
+    const end = Math.min(start + 600, source.length);
+    const window = source.slice(start, end);
+    const epMatch = window.match(/endpoint:\s*["']([^"']+)["']/);
+    if (epMatch) {
+      pairs.push({ operationId, endpoint: epMatch[1]!, sourceFile });
+    }
+  }
+  return pairs;
+}
+
+function collectAllRoutePairs(): RoutePair[] {
+  const out: RoutePair[] = [];
+  for (const file of collectRouteSourceFiles(ROUTES_DIR)) {
+    out.push(...extractRoutePairs(readFileSync(file, "utf-8"), file));
+  }
+  return out;
+}
+
+/**
+ * Strip `/:param` segments so a route's `endpoint` matches the policy
+ * key registered in route-policy.ts. The daemon's HTTP router uses the
+ * non-parameterized form as the canonical policy key.
+ *
+ * Examples:
+ *   "internal/oauth/connect/status/:state" → "internal/oauth/connect/status"
+ *   "internal/mcp/auth/status/:serverId"   → "internal/mcp/auth/status"
+ *   "profiler/runs/:runId"                 → "profiler/runs"
+ */
+function normalizeEndpoint(endpoint: string): string {
+  return endpoint.replace(/\/:[^/]+/g, "");
+}
+
+// ---------------------------------------------------------------------------
+// Step 2 — Extract gateway-only endpoints (with required scopes) from
+// daemon's route-policy.ts.
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse the daemon's route-policy.ts source to find every endpoint
+ * registered with `allowedPrincipalTypes: ["svc_gateway"]`. For each,
+ * record the `requiredScopes` array so the IPC policy can be cross-checked
+ * for scope parity (not just principal parity).
+ *
+ * Two patterns are supported:
+ *   1. Direct: `registerPolicy("endpoint", { requiredScopes: [...], ["svc_gateway"] ... })`
+ *   2. Loop:   `const X_ENDPOINTS = ["a", "b", ...]; for (const e of X_ENDPOINTS) { registerPolicy(e, { requiredScopes: [...], ["svc_gateway"] ... }) }`
+ *
+ * Pattern 2 is detected heuristically: when a `const ARRAY = [...]` is
+ * followed by a `for...of ARRAY` containing `registerPolicy(...)` and
+ * `["svc_gateway"]`, every string in the array is treated as gateway-only
+ * and shares the loop body's `requiredScopes`.
+ */
+function extractScopes(block: string): string[] | null {
+  const m = block.match(/requiredScopes:\s*\[([^\]]*)\]/);
+  if (!m) return null;
+  const scopes: string[] = [];
+  for (const lit of m[1]!.matchAll(/["']([^"']+)["']/g)) {
+    scopes.push(lit[1]!);
+  }
+  return scopes;
+}
+
+interface GatewayOnlyEntry {
+  requiredScopes: string[];
+}
+
+function extractGatewayOnlyEndpoints(): Map<string, GatewayOnlyEntry> {
+  const text = readFileSync(ROUTE_POLICY_FILE, "utf-8");
+  const out = new Map<string, GatewayOnlyEntry>();
+
+  // Pattern 1: explicit registerPolicy calls.
+  //
+  // Split the file into individual `registerPolicy(...)` blocks first
+  // (using a non-greedy match up to the next `});`) so the multi-line
+  // [\s\S]*? alternation can't accidentally span multiple registrations
+  // and pick up a "svc_gateway"-only array from a different policy.
+  const blockRegex =
+    /registerPolicy\(\s*["']([^"']+)["']\s*,\s*\{[\s\S]*?\}\s*\)\s*;/g;
+  for (const m of text.matchAll(blockRegex)) {
+    const endpoint = m[1]!;
+    const block = m[0]!;
+    // Within this single registerPolicy block, require allowedPrincipalTypes
+    // to be EXACTLY ["svc_gateway"] — no other principals.
+    if (
+      !/allowedPrincipalTypes:\s*\[\s*["']svc_gateway["']\s*\]/.test(block)
+    )
+      continue;
+    const scopes = extractScopes(block);
+    if (!scopes) continue;
+    out.set(endpoint, { requiredScopes: scopes });
+  }
+
+  // Pattern 2: const ARRAY = [...] followed by a for-of loop that
+  // registers svc_gateway-only policies for each element. Detected
+  // heuristically: when a `const ARRAY = [...]` is followed somewhere
+  // in the file by a for-of loop over that array containing both a
+  // `registerPolicy(` and a literal `["svc_gateway"]`, every string in
+  // the array is treated as gateway-only and shares the loop body's
+  // `requiredScopes`.
+  const arrayDeclRegex =
+    /const\s+([A-Z_][A-Z0-9_]*)\s*=\s*\[([\s\S]*?)\]\s*;/g;
+  for (const m of text.matchAll(arrayDeclRegex)) {
+    const arrayName = m[1]!;
+    const arrayBody = m[2]!;
+    // Find a for-of loop over this array. Use a non-greedy body match
+    // that stops at the closing `}` of the for-block.
+    const loopBlockRegex = new RegExp(
+      String.raw`for\s*\(\s*const\s+\w+\s+of\s+` +
+        arrayName +
+        String.raw`\s*\)\s*\{[\s\S]*?\}`,
+    );
+    const loopMatch = text.match(loopBlockRegex);
+    if (!loopMatch) continue;
+    const loopBody = loopMatch[0];
+    if (!loopBody.includes("registerPolicy")) continue;
+    if (!/\[\s*["']svc_gateway["']\s*\]/.test(loopBody)) continue;
+    const scopes = extractScopes(loopBody);
+    if (!scopes) continue;
+    // Extract every string literal from the array body.
+    for (const lit of arrayBody.matchAll(/["']([^"']+)["']/g)) {
+      out.set(lit[1]!, { requiredScopes: scopes });
+    }
+  }
+
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Step 3 — Cross-reference and assert.
+// ---------------------------------------------------------------------------
+
+describe("ipc-route-policy: gateway-only coverage lint", () => {
+  const gatewayOnlyEndpoints = extractGatewayOnlyEndpoints();
+  const routePairs = collectAllRoutePairs();
+
+  // Build the gateway-only operationId set by intersecting
+  // (normalized routes) ∩ (policy keys). Preserve the daemon's
+  // requiredScopes so the IPC policy can be checked for scope parity.
+  const gatewayOnlyRoutes = routePairs
+    .map((r) => {
+      const normalized = normalizeEndpoint(r.endpoint);
+      const entry = gatewayOnlyEndpoints.get(normalized);
+      if (!entry) return null;
+      return { ...r, normalizedEndpoint: normalized, daemonScopes: entry.requiredScopes };
+    })
+    .filter(
+      (r): r is RoutePair & { normalizedEndpoint: string; daemonScopes: string[] } =>
+        r !== null,
+    );
+
+  test("discovery sanity: found gateway-only daemon routes", () => {
+    // If the discovery returns zero, we'd silently pass every check
+    // below. Fail loud instead.
+    expect(gatewayOnlyEndpoints.size).toBeGreaterThan(0);
+    expect(gatewayOnlyRoutes.length).toBeGreaterThan(0);
+  });
+
+  // One test case per gateway-only route so the failure message points
+  // directly at the specific operationId that's missing coverage.
+  for (const route of gatewayOnlyRoutes) {
+    const relPath = route.sourceFile.split("/assistant/src/")[1] ?? route.sourceFile;
+    test(`${route.operationId} (endpoint=${route.endpoint}) has an IPC policy entry`, () => {
+      const policy = getIpcRoutePolicy(route.operationId);
+      expect(
+        policy,
+        `${route.operationId} is registered as a gateway-only daemon ` +
+          `route (endpoint=${route.endpoint}, defined in assistant/src/${relPath}) ` +
+          `but is missing from gateway/src/auth/ipc-route-policy.ts. ` +
+          `Add an entry: ` +
+          `["${route.operationId}", ${JSON.stringify(route.daemonScopes)}, ["svc_gateway"]] ` +
+          `to match the daemon HTTP policy.`,
+      ).toBeDefined();
+      expect(policy!.allowedPrincipalTypes).toEqual(["svc_gateway"]);
+      // Scope parity: IPC requiredScopes must match daemon requiredScopes
+      // exactly (as a set). Otherwise the IPC path could be reached with
+      // a broader/different scope than the daemon HTTP path requires,
+      // recreating the scope-bypass class this lint exists to prevent.
+      // Compare as plain string[] — Scope is a string union, but the daemon
+      // scopes come from text-parsed source so they're already string[].
+      const ipcScopes: string[] = [...policy!.requiredScopes].sort();
+      const daemonScopes: string[] = [...route.daemonScopes].sort();
+      expect(
+        ipcScopes,
+        `${route.operationId} has IPC requiredScopes=${JSON.stringify(ipcScopes)} ` +
+          `but daemon HTTP requires ${JSON.stringify(daemonScopes)}. ` +
+          `Scope mismatch makes the IPC path more permissive than the HTTP ` +
+          `path, recreating the scope-bypass class this lint prevents. ` +
+          `Update the entry in gateway/src/auth/ipc-route-policy.ts to use ` +
+          `${JSON.stringify(daemonScopes)}.`,
+      ).toEqual(daemonScopes);
+    });
+  }
+});

package/src/__tests__/ipc-route-policy.test.ts

@@ -10,15 +10,58 @@ describe("ipc-route-policy: gateway-only daemon routes", () => {
   // X-Vellum-Proxy-Server: ipc, bypassing the daemon HTTP router entirely.
   test.each([
     "admin_rollbackmigrations_post",
+    "emit_event",
     "internal_mcp_auth_start",
     "internal_mcp_auth_status",
     "internal_mcp_reload",
+    "internal_oauth_callback",
     "internal_oauth_connect_start",
     "internal_oauth_connect_status",
+    "internal_twilio_connect_action",
+    "internal_twilio_status",
+    "internal_twilio_voice_webhook",
+    "profiler_runs_get",
+    "profiler_runs_by_runId_delete",
+    "profiler_runs_by_runId_export_post",
+    "profiler_runs_by_runId_get",
+    "upgrade_broadcast",
+    "workspace_commit",
   ])("%s requires internal.write and svc_gateway", (operationId) => {
     const policy = getIpcRoutePolicy(operationId);
     expect(policy).toBeDefined();
     expect(policy!.requiredScopes).toEqual(["internal.write"]);
     expect(policy!.allowedPrincipalTypes).toEqual(["svc_gateway"]);
   });
+
+  // channels/inbound uses ingress.write rather than internal.write.
+  test("channel_inbound requires ingress.write and svc_gateway", () => {
+    const policy = getIpcRoutePolicy("channel_inbound");
+    expect(policy).toBeDefined();
+    expect(policy!.requiredScopes).toEqual(["ingress.write"]);
+    expect(policy!.allowedPrincipalTypes).toEqual(["svc_gateway"]);
+  });
+});
+
+describe("ipc-route-policy: inference provider connections", () => {
+  // The connection CRUD routes are reachable through the gateway IPC proxy,
+  // so their settings.read/settings.write scopes must be enforced there as
+  // well as on the daemon HTTP path.
+  test.each([
+    "inference_provider_connections_get",
+    "inference_provider_connections_list",
+  ])("%s requires settings.read", (operationId) => {
+    const policy = getIpcRoutePolicy(operationId);
+    expect(policy).toBeDefined();
+    expect(policy!.requiredScopes).toEqual(["settings.read"]);
+  });
+
+  test.each([
+    "inference_provider_connections_create",
+    "inference_provider_connections_delete",
+    "inference_provider_connections_update",
+  ])("%s requires settings.write", (operationId) => {
+    const policy = getIpcRoutePolicy(operationId);
+    expect(policy).toBeDefined();
+    expect(policy!.requiredScopes).toEqual(["settings.write"]);
+  });
 });

package/src/__tests__/ipc-server-watchdog.test.ts

@@ -0,0 +1,189 @@
+import { afterAll, afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdtempSync, rmSync, unlinkSync } from "node:fs";
+import { createConnection, type Socket } from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import "./test-preload.js";
+
+import { GatewayIpcServer, type IpcRoute } from "../ipc/server.js";
+
+// Integration tests for GatewayIpcServer's watchdog wiring. The watchdog's
+// own unit tests (race guards, timer error handling, etc.) live in
+// `@vellumai/ipc-server-utils`. These tests verify that the gateway server
+// correctly wires the watchdog into its own lifecycle and legacy-server
+// bookkeeping.
+
+// macOS caps Unix socket paths at sizeof(sun_path)-1 == 103 chars, so the
+// shared test-preload temp dir is too long. Mint our own short path under
+// the system tmpdir for this test.
+const shortRoot = mkdtempSync(join(tmpdir(), "vmw-"));
+const socketPath = join(shortRoot, "g.sock");
+
+afterAll(() => {
+  try {
+    rmSync(shortRoot, { recursive: true, force: true });
+  } catch {
+    // best-effort
+  }
+});
+
+function connectClient(path: string): Promise<Socket> {
+  return new Promise<Socket>((resolve, reject) => {
+    const client: Socket = createConnection(path, () => resolve(client));
+    client.on("error", reject);
+  });
+}
+
+function sendRequest(
+  client: Socket,
+  method: string,
+  params?: Record<string, unknown>,
+): Promise<{ id: string; result?: unknown; error?: string }> {
+  return new Promise((resolve, reject) => {
+    const id = randomBytes(4).toString("hex");
+    let buffer = "";
+
+    const onData = (chunk: Buffer) => {
+      buffer += chunk.toString();
+      const newlineIdx = buffer.indexOf("\n");
+      if (newlineIdx !== -1) {
+        const line = buffer.slice(0, newlineIdx).trim();
+        buffer = buffer.slice(newlineIdx + 1);
+        client.off("data", onData);
+        try {
+          resolve(JSON.parse(line));
+        } catch (err) {
+          reject(err);
+        }
+      }
+    };
+
+    client.on("data", onData);
+    client.write(JSON.stringify({ id, method, params }) + "\n");
+  });
+}
+
+const echoRoute: IpcRoute = {
+  method: "echo",
+  handler: (params) => ({ echoed: params?.value ?? null }),
+};
+
+/**
+ * Build a server with the test-owned short socket path. The constructor
+ * resolves the path via env-var defaults that may not point at our temp
+ * dir, so we override the private `socketPath` field directly — same
+ * pattern used by `ipc-server-multi-client.test.ts`.
+ *
+ * Note: the watchdog is constructed in the GatewayIpcServer constructor
+ * and captures the original (unmocked) socketPath via closure. Tests that
+ * exercise the watchdog must therefore disable the timer-driven path and
+ * use the public `rebindIfMissing()` entry point, which reads
+ * `this.socketPath` lazily through the watchdog's `socketPath` capture —
+ * which we also need to monkeypatch. See {@link buildServer}.
+ */
+function buildServer(opts: { watchdogIntervalMs: number }): GatewayIpcServer {
+  const server = new GatewayIpcServer([echoRoute], {
+    watchdogIntervalMs: opts.watchdogIntervalMs,
+  });
+  // The watchdog captures socketPath in its constructor, so override both
+  // the public field (for start()/stop()) and the watchdog's private copy.
+  (server as unknown as { socketPath: string }).socketPath = socketPath;
+  const watchdog = (server as unknown as { watchdog: { socketPath: string } })
+    .watchdog;
+  watchdog.socketPath = socketPath;
+  return server;
+}
+
+async function waitForListening(path: string, timeoutMs = 1000): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (!existsSync(path) && Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, 5));
+  }
+  if (!existsSync(path)) {
+    throw new Error(`server did not bind ${path} within ${timeoutMs}ms`);
+  }
+}
+
+describe("GatewayIpcServer watchdog wiring", () => {
+  let server: GatewayIpcServer | undefined;
+  const sockets: Socket[] = [];
+
+  beforeEach(() => {
+    server = undefined;
+  });
+
+  afterEach(() => {
+    for (const s of sockets) {
+      if (!s.destroyed) s.destroy();
+    }
+    sockets.length = 0;
+
+    if (server) {
+      server.stop();
+      server = undefined;
+    }
+
+    if (existsSync(socketPath)) {
+      try {
+        unlinkSync(socketPath);
+      } catch {
+        // ignore
+      }
+    }
+  });
+
+  test("rebindIfMissing restores the listener and accepts new clients end-to-end", async () => {
+    server = buildServer({ watchdogIntervalMs: 0 });
+    server.start();
+    await waitForListening(socketPath);
+
+    // A baseline client confirms the initial listener is healthy.
+    const baseline = await connectClient(socketPath);
+    sockets.push(baseline);
+    const baselineEcho = await sendRequest(baseline, "echo", { value: "pre" });
+    expect(baselineEcho.result).toEqual({ echoed: "pre" });
+
+    // Simulate the cleanup that wipes /run/* — unlink the socket file
+    // while the listening fd is still alive in the kernel.
+    unlinkSync(socketPath);
+    expect(existsSync(socketPath)).toBe(false);
+
+    const rebound = await server.rebindIfMissing();
+    expect(rebound).toBe(true);
+    expect(existsSync(socketPath)).toBe(true);
+
+    // A new client can connect to the re-bound listener and exercise the
+    // route table — proving onRebind correctly installed the new server
+    // as the primary.
+    const fresh = await connectClient(socketPath);
+    sockets.push(fresh);
+    const freshEcho = await sendRequest(fresh, "echo", { value: "post" });
+    expect(freshEcho.result).toEqual({ echoed: "post" });
+
+    // The pre-existing client survives the rebind because its connected
+    // socket inode lives independently of the listener path.
+    expect(baseline.destroyed).toBe(false);
+  });
+
+  test("stop() halts the watchdog so a later unlink does not resurrect the listener", async () => {
+    server = buildServer({ watchdogIntervalMs: 10 });
+    server.start();
+    await waitForListening(socketPath);
+
+    server.stop();
+    expect(existsSync(socketPath)).toBe(false);
+
+    // Even if something recreated and removed the path again, the watchdog
+    // has been stopped and rebindIfMissing returns false because the
+    // server reference was nulled.
+    const rebound = await server.rebindIfMissing();
+    expect(rebound).toBe(false);
+    expect(existsSync(socketPath)).toBe(false);
+
+    // Wait past several timer ticks to confirm no background rebind fires.
+    await new Promise((r) => setTimeout(r, 50));
+    expect(existsSync(socketPath)).toBe(false);
+  });
+});

package/src/__tests__/live-voice-websocket.test.ts

@@ -422,7 +422,7 @@ describe("live voice gateway boundary", () => {
       'url.pathname === "/v1/live-voice"',
     );
     const runtimeProxyDispatchIndex = source.indexOf(
-      "const response = router(req, url, resolveClientIp, svr);",
+      "const response = await router(req, url, resolveClientIp, svr);",
     );
 
     expect(liveVoiceRouteIndex).toBeGreaterThan(-1);

package/src/__tests__/slack-normalize.test.ts

@@ -528,4 +528,136 @@ describe("normalizeSlackMessageEdit", () => {
     expect(result).not.toBeNull();
     expect(result!.event.source.chatType).toBeUndefined();
   });
+
+  test("returns null for metadata-only mutation on a never-edited message", () => {
+    const config = makeConfig();
+    const event = makeMessageChangedEvent({
+      message: {
+        user: "U_USER123",
+        text: "<@UBOT> can you take a look",
+        ts: "1700000000.000100",
+      },
+      previous_message: {
+        user: "U_USER123",
+        text: "<@UBOT> can you take a look",
+        ts: "1700000000.000100",
+      },
+    });
+    const result = normalizeSlackMessageEdit(
+      event,
+      "evt-metadata-only-1",
+      config,
+    );
+
+    expect(result).toBeNull();
+  });
+
+  test("returns null for metadata-only mutation on an already-edited message", () => {
+    const config = makeConfig();
+    const event = makeMessageChangedEvent({
+      message: {
+        user: "U_USER123",
+        text: "<@UBOT> can you take a look",
+        ts: "1700000000.000100",
+        edited: { user: "U_USER123", ts: "1700000000.000150" },
+      },
+      previous_message: {
+        user: "U_USER123",
+        text: "<@UBOT> can you take a look",
+        ts: "1700000000.000100",
+        edited: { user: "U_USER123", ts: "1700000000.000150" },
+      },
+    });
+    const result = normalizeSlackMessageEdit(
+      event,
+      "evt-metadata-only-2",
+      config,
+    );
+
+    expect(result).toBeNull();
+  });
+
+  test("returns null for metadata-only mutation in a DM", () => {
+    const config = makeConfig();
+    const event = makeMessageChangedEvent({
+      channel: "D_DM_CHANNEL",
+      channel_type: "im",
+      message: {
+        user: "U_USER123",
+        text: "hey, free for a quick sync?",
+        ts: "1700000000.000100",
+      },
+      previous_message: {
+        user: "U_USER123",
+        text: "hey, free for a quick sync?",
+        ts: "1700000000.000100",
+      },
+    });
+    const result = normalizeSlackMessageEdit(
+      event,
+      "evt-metadata-only-dm",
+      config,
+    );
+
+    expect(result).toBeNull();
+  });
+
+  test("forwards first user edit when message.edited becomes set", () => {
+    const config = makeConfig();
+    const event = makeMessageChangedEvent({
+      message: {
+        user: "U_USER123",
+        text: "<@UBOT> can you take another look",
+        ts: "1700000000.000100",
+        edited: { user: "U_USER123", ts: "1700000000.000200" },
+      },
+      previous_message: {
+        user: "U_USER123",
+        text: "<@UBOT> can you take a look",
+        ts: "1700000000.000100",
+      },
+    });
+    const result = normalizeSlackMessageEdit(event, "evt-real-edit-1", config);
+
+    expect(result).not.toBeNull();
+    expect(result!.event.message.content).toContain(
+      "can you take another look",
+    );
+    expect(result!.event.message.isEdit).toBe(true);
+  });
+
+  test("forwards rich-text-only edit when text is identical but edited.ts changes", () => {
+    const config = makeConfig();
+    const event = makeMessageChangedEvent({
+      message: {
+        user: "U_USER123",
+        text: "<@UBOT> can you take a look",
+        ts: "1700000000.000100",
+        edited: { user: "U_USER123", ts: "1700000000.000200" },
+      },
+      previous_message: {
+        user: "U_USER123",
+        text: "<@UBOT> can you take a look",
+        ts: "1700000000.000100",
+      },
+    });
+    const result = normalizeSlackMessageEdit(
+      event,
+      "evt-rich-text-edit",
+      config,
+    );
+
+    expect(result).not.toBeNull();
+    expect(result!.event.message.isEdit).toBe(true);
+  });
+
+  test("forwards edit when previous_message is missing (cannot prove no-op)", () => {
+    const config = makeConfig();
+    const event = makeMessageChangedEvent();
+    expect(event.previous_message).toBeUndefined();
+
+    const result = normalizeSlackMessageEdit(event, "evt-no-prev", config);
+    expect(result).not.toBeNull();
+    expect(result!.event.message.isEdit).toBe(true);
+  });
 });