@vellumai/vellum-gateway 0.7.0 → 0.7.2

package/src/__tests__/pair-origin-allowlist.test.ts

@@ -0,0 +1,155 @@
+/**
+ * Tests for ATL-433: /v1/pair validates Origin against KNOWN_EXTENSION_ORIGINS,
+ * and resolveExtensionOrigin uses the same allowlist.
+ */
+import { describe, test, expect, mock, beforeEach } from "bun:test";
+
+import { initSigningKey } from "../auth/token-service.js";
+
+// Must init signing key before any module that mints tokens is imported.
+initSigningKey(Buffer.from("test-signing-key-at-least-32-bytes-long-xx"));
+
+// Mock DB — pair.ts calls resolveLocalGuardianPrincipalId() which queries the DB.
+const mockQuery = mock();
+mock.module("../db/assistant-db-proxy.js", () => ({
+  assistantDbQuery: mockQuery,
+  assistantDbRun: mock(),
+  assistantDbExec: mock(),
+}));
+
+const { handlePair, resetPairRateLimiterForTests } = await import(
+  "../http/routes/pair.js"
+);
+const { resolveExtensionOrigin } = await import(
+  "../http/middleware/cors.js"
+);
+const { KNOWN_EXTENSION_ORIGINS } = await import(
+  "../chrome-extension-origins.js"
+);
+
+// Simulate a loopback peer IP as supplied by the gateway server to the handler.
+const LOOPBACK_IP = "127.0.0.1";
+
+// A valid Vellum extension origin (production).
+const PROD_ORIGIN = "chrome-extension://hphbdmpffeigpcdjkckleobjmhhokpne";
+// A non-Vellum extension origin.
+const MALICIOUS_ORIGIN = "chrome-extension://aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
+
+function makePairRequest(overrides: {
+  method?: string;
+  origin?: string | null;
+  interfaceId?: string | null;
+  xForwardedFor?: string;
+} = {}): Request {
+  const { method = "POST", origin, interfaceId = "chrome-extension", xForwardedFor } = overrides;
+  const headers: Record<string, string> = {
+    "host": "localhost:7830",
+    "content-type": "application/json",
+  };
+  if (origin !== null) {
+    headers["origin"] = origin ?? PROD_ORIGIN;
+  }
+  if (interfaceId !== null) {
+    headers["x-vellum-interface-id"] = interfaceId;
+  }
+  if (xForwardedFor) {
+    headers["x-forwarded-for"] = xForwardedFor;
+  }
+  return new Request("http://localhost:7830/v1/pair", { method, headers });
+}
+
+beforeEach(() => {
+  resetPairRateLimiterForTests();
+  mockQuery.mockResolvedValue([{ principalId: "guardian-001" }]);
+});
+
+// ---------------------------------------------------------------------------
+// resolveExtensionOrigin — allowlist behaviour
+// ---------------------------------------------------------------------------
+
+describe("resolveExtensionOrigin", () => {
+  test("returns origin for every known Vellum extension ID", () => {
+    for (const origin of KNOWN_EXTENSION_ORIGINS) {
+      const req = new Request("http://localhost:7830/v1/events", {
+        headers: { origin },
+      });
+      expect(resolveExtensionOrigin(req)).toBe(origin);
+    }
+  });
+
+  test("returns null for an unknown chrome-extension:// origin", () => {
+    const req = new Request("http://localhost:7830/v1/events", {
+      headers: { origin: MALICIOUS_ORIGIN },
+    });
+    expect(resolveExtensionOrigin(req)).toBeNull();
+  });
+
+  test("returns null when Origin header is absent", () => {
+    const req = new Request("http://localhost:7830/v1/events");
+    expect(resolveExtensionOrigin(req)).toBeNull();
+  });
+
+  test("returns null for a non-extension origin (web page)", () => {
+    const req = new Request("http://localhost:7830/v1/events", {
+      headers: { origin: "https://evil.example.com" },
+    });
+    expect(resolveExtensionOrigin(req)).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// /v1/pair — Origin check for chrome-extension interface
+// ---------------------------------------------------------------------------
+
+describe("handlePair — Origin allowlist", () => {
+  test("pairs successfully with a known prod extension origin", async () => {
+    const req = makePairRequest({ origin: PROD_ORIGIN });
+    const res = await handlePair(req, LOOPBACK_IP);
+    expect(res.status).toBe(200);
+    const body = await res.json() as Record<string, unknown>;
+    expect(typeof body.token).toBe("string");
+  });
+
+  test("pairs successfully with each known extension origin", async () => {
+    for (const origin of KNOWN_EXTENSION_ORIGINS) {
+      resetPairRateLimiterForTests();
+      const req = makePairRequest({ origin });
+      const res = await handlePair(req, LOOPBACK_IP);
+      expect(res.status).toBe(200);
+    }
+  });
+
+  test("rejects a request from an unknown extension origin with 403", async () => {
+    const req = makePairRequest({ origin: MALICIOUS_ORIGIN });
+    const res = await handlePair(req, LOOPBACK_IP);
+    expect(res.status).toBe(403);
+    const body = await res.json() as Record<string, unknown>;
+    expect((body.error as Record<string, unknown>).code).toBe("FORBIDDEN");
+  });
+
+  test("rejects a request with no Origin header with 403", async () => {
+    const req = makePairRequest({ origin: null });
+    const res = await handlePair(req, LOOPBACK_IP);
+    expect(res.status).toBe(403);
+  });
+
+  test("still rejects non-loopback callers regardless of origin", async () => {
+    const req = makePairRequest({ origin: PROD_ORIGIN });
+    const res = await handlePair(req, "8.8.8.8");
+    expect(res.status).toBe(403);
+    const body = await res.json() as Record<string, unknown>;
+    expect((body.error as Record<string, unknown>).code).toBe("FORBIDDEN");
+  });
+
+  test("still rejects requests with X-Forwarded-For regardless of origin", async () => {
+    const req = makePairRequest({ origin: PROD_ORIGIN, xForwardedFor: "1.2.3.4" });
+    const res = await handlePair(req, LOOPBACK_IP);
+    expect(res.status).toBe(403);
+  });
+
+  test("still rejects unknown interface IDs (unrelated to origin check)", async () => {
+    const req = makePairRequest({ origin: PROD_ORIGIN, interfaceId: "unknown-client" });
+    const res = await handlePair(req, LOOPBACK_IP);
+    expect(res.status).toBe(400);
+  });
+});

package/src/__tests__/rate-limit-loopback.test.ts

@@ -49,7 +49,7 @@ describe("checkAuthRateLimit loopback exemption", () => {
     const ip = "203.0.113.5";
     const limiter = blockedLimiter(ip);
     const res = checkAuthRateLimit(
-      new URL("http://local/v1/browser-relay"),
+      new URL("http://local/health"),
       limiter,
       ip,
     );

package/src/__tests__/remote-feature-flag-sync.test.ts

@@ -1,5 +1,6 @@
 import { describe, test, expect, mock, beforeEach, afterEach } from "bun:test";
-import { mkdirSync, rmSync } from "node:fs";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
 
 import type { CredentialCache } from "../credential-cache.js";
 
@@ -32,6 +33,37 @@ const { RemoteFeatureFlagSync } =
   await import("../remote-feature-flag-sync.js");
 const { readRemoteFeatureFlags, clearRemoteFeatureFlagStoreCache } =
   await import("../feature-flag-remote-store.js");
+const { resetFeatureFlagDefaultsCache, _setRegistryCandidateOverrides } =
+  await import("../feature-flag-defaults.js");
+
+// ---------------------------------------------------------------------------
+// Test-local registry with a GA flag (defaultEnabled: true) for the
+// "ignores remote false for GA flags" test. Written to an isolated temp path
+// so we never touch the committed registry file.
+// ---------------------------------------------------------------------------
+const testRegistryPath = join(protectedDir, "feature-flag-registry.json");
+
+const TEST_REGISTRY = {
+  version: 1,
+  flags: [
+    {
+      id: "test-ga-flag",
+      scope: "assistant",
+      key: "test-ga-flag",
+      label: "Test GA Flag",
+      description: "A test flag that is GA (defaultEnabled: true)",
+      defaultEnabled: true,
+    },
+    {
+      id: "email-channel",
+      scope: "assistant",
+      key: "email-channel",
+      label: "Email Channel",
+      description: "Email channel integration",
+      defaultEnabled: false,
+    },
+  ],
+};
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -92,6 +124,10 @@ beforeEach(() => {
   delete process.env.VELLUM_PLATFORM_URL;
   delete process.env.PLATFORM_INTERNAL_API_KEY;
   mkdirSync(protectedDir, { recursive: true });
+  // Write the test registry and point resolution at it
+  writeFileSync(testRegistryPath, JSON.stringify(TEST_REGISTRY, null, 2));
+  _setRegistryCandidateOverrides([testRegistryPath]);
+  resetFeatureFlagDefaultsCache();
   clearRemoteFeatureFlagStoreCache();
   fetchMock = mock(async () => new Response());
 });
@@ -113,6 +149,8 @@ afterEach(() => {
   } catch {
     // best effort cleanup
   }
+  _setRegistryCandidateOverrides(null);
+  resetFeatureFlagDefaultsCache();
   clearRemoteFeatureFlagStoreCache();
 });
 
@@ -423,15 +461,17 @@ describe("RemoteFeatureFlagSync", () => {
     // The platform sends false for all flags it knows about (blanket-deny).
     // GA flags (defaultEnabled: true in the registry) should not be disabled
     // by remote overrides — only local persisted overrides can do that.
+    // Uses the test-local registry which defines test-ga-flag as GA
+    // (defaultEnabled: true) and email-channel as gated (defaultEnabled: false).
     fetchMock = mock(async () =>
       Response.json({
         flags: {
           // GA flag (defaultEnabled: true) — remote false should be dropped
-          "conversation-starters": false,
+          "test-ga-flag": false,
           // Gated flag (defaultEnabled: false) — remote false is kept
           "email-channel": false,
           // GA flag set to true — should be kept (redundant but harmless)
-          browser: true,
+          "test-ga-flag-true": true,
           // Unknown flag — remote false is kept (not in registry)
           "unknown-flag": false,
         },
@@ -446,12 +486,12 @@ describe("RemoteFeatureFlagSync", () => {
 
     clearRemoteFeatureFlagStoreCache();
     const cached = readRemoteFeatureFlags();
-    // conversation-starters (GA, remote false) should be absent
-    expect(cached["conversation-starters"]).toBeUndefined();
+    // test-ga-flag (GA, remote false) should be absent
+    expect(cached["test-ga-flag"]).toBeUndefined();
     // email-channel (gated, remote false) should be present
     expect(cached["email-channel"]).toBe(false);
-    // browser (GA, remote true) should be present
-    expect(cached.browser).toBe(true);
+    // test-ga-flag-true (unknown but true) should be present
+    expect(cached["test-ga-flag-true"]).toBe(true);
     // unknown-flag (not in registry, remote false) should be present
     expect(cached["unknown-flag"]).toBe(false);
   });

package/src/__tests__/resolve-assistant.test.ts

@@ -9,7 +9,6 @@ function makeConfig(overrides: Partial<GatewayConfig> = {}): GatewayConfig {
     defaultAssistantId: undefined,
     unmappedPolicy: "reject",
     port: 7830,
-    runtimeProxyEnabled: false,
     runtimeProxyRequireAuth: true,
     shutdownDrainMs: 5000,
     runtimeTimeoutMs: 30000,

package/src/__tests__/route-schema-guard.test.ts

@@ -1,6 +1,13 @@
 import { describe, test, expect } from "bun:test";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
+import {
+  TWILIO_CONNECT_ACTION_WEBHOOK_PATH,
+  TWILIO_MEDIA_STREAM_WEBHOOK_PATH,
+  TWILIO_RELAY_WEBHOOK_PATH,
+  TWILIO_STATUS_WEBHOOK_PATH,
+  TWILIO_VOICE_WEBHOOK_PATH,
+} from "@vellumai/service-contracts/twilio-ingress";
 import { buildSchema } from "../schema.js";
 
 /** A route extracted from source: path + optional HTTP method. */
@@ -9,6 +16,14 @@ interface ExtractedRoute {
   method: string | null; // null means "any method"
 }
 
+const ROUTE_PATH_CONSTANTS: Record<string, string> = {
+  TWILIO_CONNECT_ACTION_WEBHOOK_PATH,
+  TWILIO_MEDIA_STREAM_WEBHOOK_PATH,
+  TWILIO_RELAY_WEBHOOK_PATH,
+  TWILIO_STATUS_WEBHOOK_PATH,
+  TWILIO_VOICE_WEBHOOK_PATH,
+};
+
 /**
  * Extracts route paths from the gateway index.ts source code.
  *
@@ -40,6 +55,17 @@ function extractRoutesFromSource(): ExtractedRoute[] {
       continue;
     }
 
+    // Match shared path constants: `path: SOME_WEBHOOK_PATH`
+    const constantMatch = line.match(/path:\s*([A-Z0-9_]+)\b/);
+    const constantPath = constantMatch
+      ? ROUTE_PATH_CONSTANTS[constantMatch[1]]
+      : undefined;
+    if (constantPath) {
+      const method = findMethodNearPath(lines, i);
+      routes.push({ path: constantPath, method });
+      continue;
+    }
+
     // Match regex paths: `path: /^\/v1\/contacts\/([^/]+)$/`
     const regexMatch = line.match(/path:\s*\/\^(.*?)\$\//);
     if (regexMatch) {
@@ -57,6 +83,20 @@ function extractRoutesFromSource(): ExtractedRoute[] {
       seenPreRouterPaths.add(preRouterMatch[1]);
       routes.push({ path: preRouterMatch[1], method: null });
     }
+
+    const preRouterConstantMatch = line.match(
+      /url\.pathname\s*===\s*([A-Z0-9_]+)\b/,
+    );
+    const preRouterConstantPath = preRouterConstantMatch
+      ? ROUTE_PATH_CONSTANTS[preRouterConstantMatch[1]]
+      : undefined;
+    if (
+      preRouterConstantPath &&
+      !seenPreRouterPaths.has(preRouterConstantPath)
+    ) {
+      seenPreRouterPaths.add(preRouterConstantPath);
+      routes.push({ path: preRouterConstantPath, method: null });
+    }
   }
 
   return routes;
@@ -125,14 +165,10 @@ function regexToOpenApiPath(escaped: string): string | null {
 // ── Routes that are intentionally undocumented in the OpenAPI schema ──
 // Each entry must have a comment explaining why it's excluded.
 const EXCLUDED_FROM_SCHEMA = new Set([
-  // Browser relay WebSocket upgrade — handled pre-router, not a REST endpoint
-  "/v1/browser-relay",
-
-  // Browser extension pairing — localhost-only, no external consumers
-  "/v1/browser-extension-pair",
-
   // Runtime proxy catch-all — documented as /{path} in the schema
   "catch-all",
+  // Loopback-only pairing endpoint — not part of the public gateway API
+  "/v1/pair",
 ]);
 
 // ── Schema paths that don't map to a discrete route definition ──

package/src/__tests__/runtime-client.test.ts

@@ -38,7 +38,6 @@ function makeConfig(overrides: Partial<GatewayConfig> = {}): GatewayConfig {
     defaultAssistantId: undefined,
     unmappedPolicy: "reject",
     port: 7830,
-    runtimeProxyEnabled: false,
     runtimeProxyRequireAuth: true,
     shutdownDrainMs: 5000,
     runtimeTimeoutMs: 30000,

package/src/__tests__/runtime-health-proxy.test.ts

@@ -27,7 +27,6 @@ function makeConfig(overrides: Partial<GatewayConfig> = {}): GatewayConfig {
     defaultAssistantId: undefined,
     unmappedPolicy: "reject",
     port: 7830,
-    runtimeProxyEnabled: false,
     runtimeProxyRequireAuth: true,
     shutdownDrainMs: 5000,
     runtimeTimeoutMs: 30000,

package/src/__tests__/runtime-proxy-auth.test.ts

@@ -41,7 +41,6 @@ function makeConfig(overrides: Partial<GatewayConfig> = {}): GatewayConfig {
     defaultAssistantId: undefined,
     unmappedPolicy: "reject",
     port: 7830,
-    runtimeProxyEnabled: true,
     runtimeProxyRequireAuth: true,
     shutdownDrainMs: 5000,
     runtimeTimeoutMs: 30000,

package/src/__tests__/runtime-proxy.test.ts

@@ -27,7 +27,6 @@ function makeConfig(overrides: Partial<GatewayConfig> = {}): GatewayConfig {
     defaultAssistantId: undefined,
     unmappedPolicy: "reject",
     port: 7830,
-    runtimeProxyEnabled: true,
     runtimeProxyRequireAuth: false,
     shutdownDrainMs: 5000,
     runtimeTimeoutMs: 30000,

package/src/__tests__/slack-control-plane-proxy.test.ts

@@ -27,7 +27,6 @@ function makeConfig(overrides: Partial<GatewayConfig> = {}): GatewayConfig {
     defaultAssistantId: undefined,
     unmappedPolicy: "reject",
     port: 7830,
-    runtimeProxyEnabled: false,
     runtimeProxyRequireAuth: true,
     shutdownDrainMs: 5000,
     runtimeTimeoutMs: 30000,

package/src/__tests__/slack-display-name.test.ts

@@ -39,7 +39,6 @@ function makeConfig(overrides: Partial<GatewayConfig> = {}): GatewayConfig {
     routingEntries: [],
     runtimeInitialBackoffMs: 500,
     runtimeMaxRetries: 2,
-    runtimeProxyEnabled: false,
     runtimeProxyRequireAuth: false,
     runtimeTimeoutMs: 30000,
     shutdownDrainMs: 5000,
@@ -174,6 +173,7 @@ describe("normalizeSlackAppMention with display name", () => {
       event,
       "evt-dn-1a",
       config,
+      undefined,
       "xoxb-test",
     );
     expect(result1).not.toBeNull();
@@ -187,6 +187,7 @@ describe("normalizeSlackAppMention with display name", () => {
       event,
       "evt-dn-1b",
       config,
+      undefined,
       "xoxb-test",
     );
     expect(result2).not.toBeNull();
@@ -219,6 +220,7 @@ describe("normalizeSlackAppMention with display name", () => {
       event,
       "evt-dn-pw",
       config,
+      undefined,
       "xoxb-test",
     );
     expect(result).not.toBeNull();
@@ -226,6 +228,68 @@ describe("normalizeSlackAppMention with display name", () => {
     expect(result!.event.actor.username).toBe("testuser");
   });
 
+  test("renders cache-warmed mention labels in model-facing content", async () => {
+    fetchMock = mock(async () => {
+      return new Response(
+        JSON.stringify({
+          ok: true,
+          user: {
+            name: "leo",
+            real_name: "Leo Example",
+            profile: { display_name: "Leo" },
+          },
+        }),
+        { status: 200, headers: { "content-type": "application/json" } },
+      );
+    });
+
+    const config = makeConfig();
+    const event = makeEvent({
+      text: "<@U123BOT> <@ULEO> please look",
+    });
+    const userInfo = await resolveSlackUser("ULEO", "xoxb-test");
+
+    const result = normalizeSlackAppMention(
+      event,
+      "evt-mention-cache",
+      config,
+      "U123BOT",
+      undefined,
+      { userLabels: userInfo ? { ULEO: userInfo.displayName } : {} },
+    );
+
+    expect(result).not.toBeNull();
+    expect(result!.event.message.content).toBe("@Leo please look");
+    expect(result!.event.message.content).not.toContain("<@ULEO>");
+    expect(result!.event.message.content).not.toContain("ULEO");
+  });
+
+  test("renders unresolved mention IDs with fallback labels when lookup fails", async () => {
+    fetchMock = mock(async () => {
+      return new Response("", { status: 500 });
+    });
+
+    const config = makeConfig();
+    const event = makeEvent({
+      text: "<@U123BOT> <@UFAIL> please look",
+    });
+    const userInfo = await resolveSlackUser("UFAIL", "xoxb-test");
+
+    const result = normalizeSlackAppMention(
+      event,
+      "evt-mention-fallback",
+      config,
+      "U123BOT",
+      undefined,
+      { userLabels: userInfo ? { UFAIL: userInfo.displayName } : {} },
+    );
+
+    expect(result).not.toBeNull();
+    expect(result!.event.message.content).toBe("@unknown-user please look");
+    expect(result!.event.message.content).not.toContain("<@UFAIL>");
+    expect(result!.event.message.content).not.toContain("UFAIL");
+  });
+
   test("omits displayName when bot token is not configured", () => {
     const config = makeConfig();
     const event = makeEvent();
@@ -247,6 +311,7 @@ describe("normalizeSlackAppMention with display name", () => {
       event,
       "evt-dn-3",
       config,
+      undefined,
       "xoxb-test",
     );