@vellumai/vellum-gateway 0.7.1 → 0.7.2

package/src/__tests__/config-file-watcher.test.ts

@@ -0,0 +1,181 @@
+import { existsSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterEach, describe, expect, test } from "bun:test";
+
+import {
+  ConfigFileWatcher,
+  type ConfigChangeEvent,
+} from "../config-file-watcher.js";
+import {
+  isOnlyVelayPublicBaseUrlChange,
+  shouldSyncTwilioPhoneWebhooksAfterConfigChange,
+} from "../twilio/webhook-sync-trigger.js";
+import { testWorkspaceDir } from "./test-preload.js";
+
+const configPath = join(testWorkspaceDir, "config.json");
+
+function writeConfig(data: Record<string, unknown>): void {
+  writeFileSync(configPath, JSON.stringify(data), "utf-8");
+}
+
+function pollOnce(watcher: ConfigFileWatcher): void {
+  (
+    watcher as unknown as {
+      pollOnce: () => void;
+    }
+  ).pollOnce();
+}
+
+function makeEvent(
+  changedKeys: string[],
+  changedFields: Record<string, string[]>,
+): ConfigChangeEvent {
+  return {
+    data: {},
+    changedKeys: new Set(changedKeys),
+    changedFields: new Map(
+      Object.entries(changedFields).map(([section, fields]) => [
+        section,
+        new Set(fields),
+      ]),
+    ),
+  };
+}
+
+afterEach(() => {
+  try {
+    if (existsSync(configPath)) unlinkSync(configPath);
+  } catch {
+    // best-effort cleanup
+  }
+});
+
+describe("ConfigFileWatcher", () => {
+  test("reports shallow ingress fields changed by Velay-managed URL writes", () => {
+    writeConfig({
+      ingress: {
+        publicBaseUrl: "https://public.example.test",
+      },
+    });
+    const events: ConfigChangeEvent[] = [];
+    const watcher = new ConfigFileWatcher((event) => {
+      events.push(event);
+    });
+
+    pollOnce(watcher);
+    writeConfig({
+      ingress: {
+        publicBaseUrl: "https://velay.example.test",
+        publicBaseUrlManagedBy: "velay",
+      },
+    });
+    pollOnce(watcher);
+
+    expect(events).toHaveLength(2);
+    expect(events[1].changedKeys).toEqual(new Set(["ingress"]));
+    expect(events[1].changedFields.get("ingress")).toEqual(
+      new Set(["publicBaseUrl", "publicBaseUrlManagedBy"]),
+    );
+  });
+
+  test("reports Twilio-only fields when Velay creates ingress from scratch", () => {
+    writeConfig({
+      gateway: {
+        runtimeProxyRequireAuth: false,
+      },
+    });
+    const events: ConfigChangeEvent[] = [];
+    const watcher = new ConfigFileWatcher((event) => {
+      events.push(event);
+    });
+
+    pollOnce(watcher);
+    writeConfig({
+      gateway: {
+        runtimeProxyRequireAuth: false,
+      },
+      ingress: {
+        publicBaseUrl: "https://velay.example.test",
+        publicBaseUrlManagedBy: "velay",
+      },
+    });
+    pollOnce(watcher);
+
+    expect(events).toHaveLength(2);
+    expect(events[1].changedKeys).toEqual(new Set(["ingress"]));
+    expect(events[1].changedFields.get("ingress")).toEqual(
+      new Set(["publicBaseUrl", "publicBaseUrlManagedBy"]),
+    );
+  });
+
+  test("detects public base URL changes", () => {
+    writeConfig({
+      ingress: {
+        publicBaseUrl: "https://old-public.example.test",
+        publicBaseUrlManagedBy: "velay",
+      },
+    });
+    const events: ConfigChangeEvent[] = [];
+    const watcher = new ConfigFileWatcher((event) => {
+      events.push(event);
+    });
+
+    pollOnce(watcher);
+    writeConfig({
+      ingress: {
+        publicBaseUrl: "https://new-public.example.test",
+        publicBaseUrlManagedBy: "velay",
+      },
+    });
+    pollOnce(watcher);
+
+    expect(events).toHaveLength(2);
+    expect(events[1].changedFields.get("ingress")).toEqual(
+      new Set(["publicBaseUrl"]),
+    );
+  });
+});
+
+describe("Twilio webhook sync config-change triggers", () => {
+  test("syncs when generic public ingress changes without a Twilio override", () => {
+    const event = makeEvent(["ingress"], { ingress: ["publicBaseUrl"] });
+
+    expect(isOnlyVelayPublicBaseUrlChange(event)).toBe(false);
+    expect(shouldSyncTwilioPhoneWebhooksAfterConfigChange(event)).toBe(true);
+  });
+
+  test("syncs when the Twilio-specific public ingress changes", () => {
+    const event = makeEvent(["ingress"], {
+      ingress: ["publicBaseUrl", "publicBaseUrlManagedBy"],
+    });
+
+    expect(isOnlyVelayPublicBaseUrlChange(event)).toBe(true);
+    expect(shouldSyncTwilioPhoneWebhooksAfterConfigChange(event)).toBe(true);
+  });
+
+  test("does not sync when only the Velay manager marker changes", () => {
+    const event = makeEvent(["ingress"], {
+      ingress: ["publicBaseUrlManagedBy"],
+    });
+
+    expect(isOnlyVelayPublicBaseUrlChange(event)).toBe(true);
+    expect(shouldSyncTwilioPhoneWebhooksAfterConfigChange(event)).toBe(false);
+  });
+
+  test("syncs when Twilio phone configuration becomes available", () => {
+    const event = makeEvent(["twilio"], {
+      twilio: ["phoneNumber", "accountSid"],
+    });
+
+    expect(isOnlyVelayPublicBaseUrlChange(event)).toBe(false);
+    expect(shouldSyncTwilioPhoneWebhooksAfterConfigChange(event)).toBe(true);
+  });
+
+  test("does not sync when unrelated Twilio configuration changes", () => {
+    const event = makeEvent(["twilio"], {
+      twilio: ["assistantPhoneNumbers"],
+    });
+
+    expect(shouldSyncTwilioPhoneWebhooksAfterConfigChange(event)).toBe(false);
+  });
+});

package/src/__tests__/credential-watcher.test.ts

@@ -17,7 +17,7 @@ import {
 import { mkdirSync, renameSync, writeFileSync, rmSync } from "node:fs";
 import { hostname, tmpdir, userInfo } from "node:os";
 import { dirname, join } from "node:path";
-import type { Server } from "node:net";
+import { createServer, type Server } from "node:net";
 import { fileURLToPath } from "node:url";
 
 import { startFakeAssistantIpc } from "./fake-assistant-ipc.js";
@@ -194,8 +194,26 @@ let gatewayProc: ChildProcess | null = null;
 let port = 0;
 let fakeAssistantIpc: Server | null = null;
 
+/** Ask the OS for a free port by briefly binding to port 0. */
+function getFreePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const srv = createServer();
+    srv.listen(0, "127.0.0.1", () => {
+      const addr = srv.address();
+      if (!addr || typeof addr === "string") {
+        srv.close();
+        reject(new Error("Failed to get free port"));
+        return;
+      }
+      const p = addr.port;
+      srv.close(() => resolve(p));
+    });
+    srv.on("error", reject);
+  });
+}
+
 async function startGateway(): Promise<void> {
-  port = 49152 + Math.floor(Math.random() * 16383);
+  port = await getFreePort();
 
   const workspaceDir = join(testDir, ".vellum", "workspace");
   fakeAssistantIpc = startFakeAssistantIpc(workspaceDir);

package/src/__tests__/feature-flags-route.test.ts

@@ -488,12 +488,12 @@ describe("PATCH /v1/feature-flags/:flagKey handler", () => {
 
     const handler = createFeatureFlagsPatchHandler();
     const res = await handler(
-      new Request("http://gateway.test/v1/feature-flags/browser", {
+      new Request("http://gateway.test/v1/feature-flags/email-channel", {
         method: "PATCH",
         headers: { "content-type": "application/json" },
         body: JSON.stringify({ enabled: true }),
       }),
-      "browser",
+      "email-channel",
     );
 
     expect(res.status).toBe(200);
@@ -501,7 +501,7 @@ describe("PATCH /v1/feature-flags/:flagKey handler", () => {
 
     clearFeatureFlagStoreCache();
     const persisted = readPersistedFeatureFlags();
-    expect(persisted["browser"]).toBe(true);
+    expect(persisted["email-channel"]).toBe(true);
   });
 
   // Validation tests

package/src/__tests__/guardian-init-lockfile.test.ts

@@ -583,6 +583,7 @@ describe("guardian/reset-bootstrap", () => {
 describe("guardian/init bare-metal loopback gating", () => {
   test("rejects non-loopback clients in bare-metal mode", async () => {
     delete process.env.GUARDIAN_BOOTSTRAP_SECRET;
+    delete process.env.IS_PLATFORM;
     const handler = createChannelVerificationSessionProxyHandler(makeConfig());
     const res = await handler.handleGuardianInit(
       new Request("http://localhost:7830/v1/guardian/init", {
@@ -600,6 +601,7 @@ describe("guardian/init bare-metal loopback gating", () => {
 
   test("allows loopback clients in bare-metal mode", async () => {
     delete process.env.GUARDIAN_BOOTSTRAP_SECRET;
+    delete process.env.IS_PLATFORM;
     const handler = createChannelVerificationSessionProxyHandler(makeConfig());
     const res = await handler.handleGuardianInit(
       new Request("http://localhost:7830/v1/guardian/init", {
@@ -634,6 +636,28 @@ describe("guardian/init bare-metal loopback gating", () => {
     const body = await res.json();
     expect(body.accessToken).toBeTruthy();
   });
+
+  test("skips loopback check in platform-managed mode (IS_PLATFORM=true)", async () => {
+    delete process.env.GUARDIAN_BOOTSTRAP_SECRET;
+    process.env.IS_PLATFORM = "true";
+    try {
+      const handler = createChannelVerificationSessionProxyHandler(makeConfig());
+      const res = await handler.handleGuardianInit(
+        new Request("http://localhost:7830/v1/guardian/init", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ platform: "web", deviceId: "platform-abc123" }),
+        }),
+        "::ffff:10.112.1.68",
+      );
+
+      expect(res.status).toBe(200);
+      const body = await res.json();
+      expect(body.accessToken).toBeTruthy();
+    } finally {
+      delete process.env.IS_PLATFORM;
+    }
+  });
 });
 
 describe("guardian/init request validation", () => {

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__/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 ──