@vellumai/vellum-gateway 0.6.1 → 0.6.3

package/Dockerfile

@@ -20,6 +20,8 @@ WORKDIR /app
 
 RUN apt-get update && apt-get upgrade -y && apt-get install -y \
     ca-certificates \
+    iproute2 \
+    procps \
     && rm -rf /var/lib/apt/lists/*
 
 # Copy bun binary from builder

package/bun.lock

@@ -5,19 +5,19 @@
     "": {
       "name": "vellum-gateway",
       "dependencies": {
-        "file-type": "^21.3.0",
-        "minimatch": "^10.2.4",
-        "pino": "^9.6.0",
-        "pino-pretty": "^13.1.3",
-        "uuid": "^13.0.0",
+        "file-type": "21.3.0",
+        "minimatch": "10.2.4",
+        "pino": "9.14.0",
+        "pino-pretty": "13.1.3",
+        "uuid": "13.0.0",
       },
       "devDependencies": {
-        "@types/bun": "^1.2.4",
-        "eslint": "^10.0.0",
-        "knip": "^5.83.1",
-        "prettier": "^3.8.1",
-        "typescript": "^5.7.3",
-        "typescript-eslint": "^8.56.0",
+        "@types/bun": "1.3.9",
+        "eslint": "10.0.0",
+        "knip": "5.83.1",
+        "prettier": "3.8.1",
+        "typescript": "5.9.3",
+        "typescript-eslint": "8.56.0",
       },
     },
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/vellum-gateway",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -23,18 +23,18 @@
     "postinstall": "cd .. && (git config core.hooksPath || git config core.hooksPath .githooks 2>/dev/null || true) && ([ -f meta/feature-flags/sync-bundled-copies.ts ] && bun run meta/feature-flags/sync-bundled-copies.ts 2>/dev/null || true)"
   },
   "dependencies": {
-    "file-type": "^21.3.0",
-    "minimatch": "^10.2.4",
-    "pino": "^9.6.0",
-    "pino-pretty": "^13.1.3",
-    "uuid": "^13.0.0"
+    "file-type": "21.3.0",
+    "minimatch": "10.2.4",
+    "pino": "9.14.0",
+    "pino-pretty": "13.1.3",
+    "uuid": "13.0.0"
   },
   "devDependencies": {
-    "@types/bun": "^1.2.4",
-    "eslint": "^10.0.0",
-    "knip": "^5.83.1",
-    "prettier": "^3.8.1",
-    "typescript": "^5.7.3",
-    "typescript-eslint": "^8.56.0"
+    "@types/bun": "1.3.9",
+    "eslint": "10.0.0",
+    "knip": "5.83.1",
+    "prettier": "3.8.1",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.56.0"
   }
 }

package/src/__tests__/browser-relay-websocket.test.ts

@@ -3,6 +3,7 @@ import type { GatewayConfig } from "../config.js";
 import { initSigningKey, mintToken } from "../auth/token-service.js";
 import { CURRENT_POLICY_EPOCH } from "../auth/policy.js";
 import {
+  checkBrowserRelayAuth,
   createBrowserRelayWebsocketHandler,
   getBrowserRelayWebsocketHandlers,
   isLoopbackPeer,
@@ -11,17 +12,34 @@ import {
 const TEST_SIGNING_KEY = Buffer.from("test-signing-key-at-least-32-bytes-long");
 initSigningKey(TEST_SIGNING_KEY);
 
-/** Mint a valid edge JWT for browser relay auth. */
-function mintEdgeToken(): string {
+const TEST_ACTOR_PRINCIPAL = "guardian-actor-123";
+
+/** Mint a valid actor edge JWT for browser relay auth. */
+function mintEdgeToken(actorPrincipalId: string = "test-user"): string {
   return mintToken({
     aud: "vellum-gateway",
-    sub: "actor:test-assistant:test-user",
+    sub: `actor:test-assistant:${actorPrincipalId}`,
     scope_profile: "actor_client_v1",
     policy_epoch: CURRENT_POLICY_EPOCH,
     ttlSeconds: 300,
   });
 }
 
+/**
+ * Mint a service-style browser-relay edge token (svc:browser-relay:self).
+ * This token is valid for the gateway audience but carries no actor
+ * principal in its sub claim.
+ */
+function mintServiceEdgeToken(): string {
+  return mintToken({
+    aud: "vellum-gateway",
+    sub: "svc:browser-relay:self",
+    scope_profile: "gateway_service_v1",
+    policy_epoch: CURRENT_POLICY_EPOCH,
+    ttlSeconds: 300,
+  });
+}
+
 const WS_CONNECTING = WebSocket.CONNECTING; // 0
 const WS_OPEN = WebSocket.OPEN; // 1
 const WS_CLOSED = WebSocket.CLOSED; // 3
@@ -257,6 +275,7 @@ describe("getBrowserRelayWebsocketHandlers", () => {
       config: makeConfig({
         assistantRuntimeBaseUrl: "http://runtime.internal:7821",
       }),
+      auth: { authenticated: false, authBypassed: true },
     });
 
     handlers.open(ws as never);
@@ -275,11 +294,378 @@ describe("getBrowserRelayWebsocketHandlers", () => {
     fakeUpstream.emit("message", { data: "runtime-message" });
     expect(ws.sent).toEqual(["runtime-message"]);
   });
+
+  test("open appends guardianId query param when auth context carries one", () => {
+    const ws = createFakeDownstreamWs({
+      wsType: "browser-relay",
+      config: makeConfig({
+        assistantRuntimeBaseUrl: "http://runtime.internal:7821",
+      }),
+      auth: {
+        authenticated: true,
+        authBypassed: false,
+        guardianId: TEST_ACTOR_PRINCIPAL,
+      },
+    });
+
+    handlers.open(ws as never);
+
+    const MockWS = globalThis.WebSocket as unknown as ReturnType<typeof mock>;
+    const calledUrl = (MockWS.mock.calls[0] as unknown[])[0] as string;
+    const parsed = new URL(calledUrl);
+    expect(parsed.protocol).toBe("ws:");
+    expect(parsed.host).toBe("runtime.internal:7821");
+    expect(parsed.pathname).toBe("/v1/browser-relay");
+    expect(parsed.searchParams.get("token")).toMatch(/^ey/);
+    expect(parsed.searchParams.get("guardianId")).toBe(TEST_ACTOR_PRINCIPAL);
+  });
+
+  test("open omits guardianId query param when auth context has none (auth-bypass context)", () => {
+    const ws = createFakeDownstreamWs({
+      wsType: "browser-relay",
+      config: makeConfig({
+        assistantRuntimeBaseUrl: "http://runtime.internal:7821",
+      }),
+      auth: { authenticated: true, authBypassed: false },
+    });
+
+    handlers.open(ws as never);
+
+    const MockWS = globalThis.WebSocket as unknown as ReturnType<typeof mock>;
+    const calledUrl = (MockWS.mock.calls[0] as unknown[])[0] as string;
+    const parsed = new URL(calledUrl);
+    // Auth-bypass contexts may omit guardianId; open() should not
+    // synthesize one.
+    expect(parsed.searchParams.has("guardianId")).toBe(false);
+  });
+
+  test("open appends clientInstanceId query param when auth context carries one", () => {
+    const ws = createFakeDownstreamWs({
+      wsType: "browser-relay",
+      config: makeConfig({
+        assistantRuntimeBaseUrl: "http://runtime.internal:7821",
+      }),
+      auth: {
+        authenticated: true,
+        authBypassed: false,
+        guardianId: TEST_ACTOR_PRINCIPAL,
+        clientInstanceId: "install-ABC-123",
+      },
+    });
+
+    handlers.open(ws as never);
+
+    const MockWS = globalThis.WebSocket as unknown as ReturnType<typeof mock>;
+    const calledUrl = (MockWS.mock.calls[0] as unknown[])[0] as string;
+    const parsed = new URL(calledUrl);
+    expect(parsed.pathname).toBe("/v1/browser-relay");
+    // Both guardianId and clientInstanceId should ride alongside the
+    // upstream service token, matching the runtime's accepted query
+    // param names.
+    expect(parsed.searchParams.get("guardianId")).toBe(TEST_ACTOR_PRINCIPAL);
+    expect(parsed.searchParams.get("clientInstanceId")).toBe("install-ABC-123");
+  });
+
+  test("open forwards clientInstanceId even without a guardianId", () => {
+    // Auth-bypass paths can still carry a
+    // clientInstanceId lifted from the downstream handshake. The
+    // gateway must propagate it so the runtime's multi-instance
+    // registry keys the connection correctly.
+    const ws = createFakeDownstreamWs({
+      wsType: "browser-relay",
+      config: makeConfig({
+        assistantRuntimeBaseUrl: "http://runtime.internal:7821",
+      }),
+      auth: {
+        authenticated: false,
+        authBypassed: true,
+        clientInstanceId: "install-XYZ-789",
+      },
+    });
+
+    handlers.open(ws as never);
+
+    const MockWS = globalThis.WebSocket as unknown as ReturnType<typeof mock>;
+    const calledUrl = (MockWS.mock.calls[0] as unknown[])[0] as string;
+    const parsed = new URL(calledUrl);
+    expect(parsed.searchParams.has("guardianId")).toBe(false);
+    expect(parsed.searchParams.get("clientInstanceId")).toBe("install-XYZ-789");
+  });
+
+  test("open omits clientInstanceId query param when auth context has none", () => {
+    const ws = createFakeDownstreamWs({
+      wsType: "browser-relay",
+      config: makeConfig({
+        assistantRuntimeBaseUrl: "http://runtime.internal:7821",
+      }),
+      auth: {
+        authenticated: true,
+        authBypassed: false,
+        guardianId: TEST_ACTOR_PRINCIPAL,
+      },
+    });
+
+    handlers.open(ws as never);
+
+    const MockWS = globalThis.WebSocket as unknown as ReturnType<typeof mock>;
+    const calledUrl = (MockWS.mock.calls[0] as unknown[])[0] as string;
+    const parsed = new URL(calledUrl);
+    // Older extension builds (or dev bypass paths) do not emit a
+    // clientInstanceId — the gateway must not synthesize one or send
+    // an empty string, both of which would break the runtime's
+    // legacy-key fallback semantics.
+    expect(parsed.searchParams.has("clientInstanceId")).toBe(false);
+  });
+});
+
+describe("checkBrowserRelayAuth", () => {
+  test("returns structured auth context with guardianId for actor edge tokens", () => {
+    const token = mintEdgeToken(TEST_ACTOR_PRINCIPAL);
+    const config = makeConfig({});
+    const req = new Request(
+      `http://localhost:7830/v1/browser-relay?token=${token}`,
+      { headers: { upgrade: "websocket" } },
+    );
+    const url = new URL(req.url);
+
+    const result = checkBrowserRelayAuth(req, url, config);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) throw new Error("expected ok");
+    expect(result.context.authenticated).toBe(true);
+    expect(result.context.authBypassed).toBe(false);
+    expect(result.context.guardianId).toBe(TEST_ACTOR_PRINCIPAL);
+  });
+
+  test("rejects service-style edge tokens with no actor principal", () => {
+    const token = mintServiceEdgeToken();
+    const config = makeConfig({});
+    const req = new Request(
+      `http://localhost:7830/v1/browser-relay?token=${token}`,
+      { headers: { upgrade: "websocket" } },
+    );
+    const url = new URL(req.url);
+
+    const result = checkBrowserRelayAuth(req, url, config);
+
+    expect(result.ok).toBe(false);
+    if (result.ok) throw new Error("expected error");
+    expect(result.response.status).toBe(401);
+  });
+
+  test("returns error response when token is missing and auth is required", () => {
+    const config = makeConfig({});
+    const req = new Request("http://localhost:7830/v1/browser-relay", {
+      headers: { upgrade: "websocket" },
+    });
+    const url = new URL(req.url);
+
+    const result = checkBrowserRelayAuth(req, url, config);
+
+    expect(result.ok).toBe(false);
+    if (result.ok) throw new Error("expected error");
+    expect(result.response.status).toBe(401);
+  });
+
+  test("returns bypassed context when runtimeProxyRequireAuth is disabled", () => {
+    const config = makeConfig({ runtimeProxyRequireAuth: false });
+    const req = new Request("http://localhost:7830/v1/browser-relay", {
+      headers: { upgrade: "websocket" },
+    });
+    const url = new URL(req.url);
+
+    const result = checkBrowserRelayAuth(req, url, config);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) throw new Error("expected ok");
+    expect(result.context.authBypassed).toBe(true);
+    expect(result.context.authenticated).toBe(false);
+    expect(result.context.guardianId).toBeUndefined();
+  });
+
+  test("lifts clientInstanceId from the query param on the downstream handshake", () => {
+    // Primary path: the Chrome extension sets clientInstanceId as a
+    // query param via `buildUrl`. The gateway must lift it off the
+    // handshake and expose it on the auth context so the open()
+    // handler can forward it to the runtime.
+    const token = mintEdgeToken(TEST_ACTOR_PRINCIPAL);
+    const config = makeConfig({});
+    const req = new Request(
+      `http://localhost:7830/v1/browser-relay?token=${token}&clientInstanceId=install-QUERY`,
+      { headers: { upgrade: "websocket" } },
+    );
+    const url = new URL(req.url);
+
+    const result = checkBrowserRelayAuth(req, url, config);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) throw new Error("expected ok");
+    expect(result.context.clientInstanceId).toBe("install-QUERY");
+    expect(result.context.guardianId).toBe(TEST_ACTOR_PRINCIPAL);
+  });
+
+  test("lifts clientInstanceId from the x-client-instance-id header", () => {
+    const token = mintEdgeToken(TEST_ACTOR_PRINCIPAL);
+    const config = makeConfig({});
+    const req = new Request(
+      `http://localhost:7830/v1/browser-relay?token=${token}`,
+      {
+        headers: {
+          upgrade: "websocket",
+          "x-client-instance-id": "install-HEADER",
+        },
+      },
+    );
+    const url = new URL(req.url);
+
+    const result = checkBrowserRelayAuth(req, url, config);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) throw new Error("expected ok");
+    expect(result.context.clientInstanceId).toBe("install-HEADER");
+  });
+
+  test("prefers x-client-instance-id header over query param when both are present", () => {
+    const token = mintEdgeToken(TEST_ACTOR_PRINCIPAL);
+    const config = makeConfig({});
+    const req = new Request(
+      `http://localhost:7830/v1/browser-relay?token=${token}&clientInstanceId=install-QUERY`,
+      {
+        headers: {
+          upgrade: "websocket",
+          "x-client-instance-id": "install-HEADER",
+        },
+      },
+    );
+    const url = new URL(req.url);
+
+    const result = checkBrowserRelayAuth(req, url, config);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) throw new Error("expected ok");
+    // The header form is considered the more explicit signal when
+    // both are set, matching the runtime's own precedence.
+    expect(result.context.clientInstanceId).toBe("install-HEADER");
+  });
+
+  test("treats an empty clientInstanceId query param as absent", () => {
+    const token = mintEdgeToken(TEST_ACTOR_PRINCIPAL);
+    const config = makeConfig({});
+    const req = new Request(
+      `http://localhost:7830/v1/browser-relay?token=${token}&clientInstanceId=`,
+      { headers: { upgrade: "websocket" } },
+    );
+    const url = new URL(req.url);
+
+    const result = checkBrowserRelayAuth(req, url, config);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) throw new Error("expected ok");
+    expect(result.context.clientInstanceId).toBeUndefined();
+  });
+
+  test("returns undefined clientInstanceId when neither form is present", () => {
+    const token = mintEdgeToken(TEST_ACTOR_PRINCIPAL);
+    const config = makeConfig({});
+    const req = new Request(
+      `http://localhost:7830/v1/browser-relay?token=${token}`,
+      { headers: { upgrade: "websocket" } },
+    );
+    const url = new URL(req.url);
+
+    const result = checkBrowserRelayAuth(req, url, config);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) throw new Error("expected ok");
+    expect(result.context.clientInstanceId).toBeUndefined();
+  });
+
+  test("lifts clientInstanceId even on the auth-bypass path", () => {
+    // When runtime proxy auth is disabled, the gateway still needs to
+    // propagate the per-install identifier so multi-instance routing
+    // continues to work in dev-bypass environments.
+    const config = makeConfig({ runtimeProxyRequireAuth: false });
+    const req = new Request(
+      "http://localhost:7830/v1/browser-relay?clientInstanceId=install-BYPASS",
+      { headers: { upgrade: "websocket" } },
+    );
+    const url = new URL(req.url);
+
+    const result = checkBrowserRelayAuth(req, url, config);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) throw new Error("expected ok");
+    expect(result.context.authBypassed).toBe(true);
+    expect(result.context.clientInstanceId).toBe("install-BYPASS");
+  });
+});
+
+describe("createBrowserRelayWebsocketHandler guardian propagation", () => {
+  test("upgrades with guardianId populated in auth context for actor edge tokens", () => {
+    const token = mintEdgeToken(TEST_ACTOR_PRINCIPAL);
+    const config = makeConfig({});
+    const handler = createBrowserRelayWebsocketHandler(config);
+    const req = new Request(
+      `http://localhost:7830/v1/browser-relay?token=${token}`,
+      { headers: { upgrade: "websocket" } },
+    );
+
+    let capturedData: unknown = null;
+    const fakeServer = {
+      requestIP: mock(() => ({
+        address: "127.0.0.1",
+        family: "IPv4",
+        port: 54000,
+      })),
+      upgrade: mock((_req: Request, opts?: { data?: unknown }) => {
+        capturedData = opts?.data;
+        return true;
+      }),
+    } as unknown as import("bun").Server<any>;
+
+    const res = handler(req, fakeServer);
+
+    expect(res).toBeUndefined();
+    expect(fakeServer.upgrade).toHaveBeenCalledTimes(1);
+    expect(capturedData).toMatchObject({
+      wsType: "browser-relay",
+      auth: {
+        authenticated: true,
+        authBypassed: false,
+        guardianId: TEST_ACTOR_PRINCIPAL,
+      },
+    });
+  });
+
+  test("rejects service-style edge tokens before upgrade", () => {
+    const token = mintServiceEdgeToken();
+    const config = makeConfig({});
+    const handler = createBrowserRelayWebsocketHandler(config);
+    const req = new Request(
+      `http://localhost:7830/v1/browser-relay?token=${token}`,
+      { headers: { upgrade: "websocket" } },
+    );
+
+    const fakeServer = {
+      requestIP: mock(() => ({
+        address: "127.0.0.1",
+        family: "IPv4",
+        port: 54000,
+      })),
+      upgrade: mock(() => true),
+    } as unknown as import("bun").Server<any>;
+
+    const res = handler(req, fakeServer);
+
+    expect(res).toBeInstanceOf(Response);
+    expect(res!.status).toBe(401);
+    expect(fakeServer.upgrade).not.toHaveBeenCalled();
+  });
 });
 
 describe("isLoopbackPeer", () => {
   test("uses x-forwarded-for first hop when trustProxy is enabled", () => {
-    const req = new Request("http://localhost:7830/v1/browser-relay/token", {
+    const req = new Request("http://localhost:7830/v1/browser-relay", {
       headers: { "x-forwarded-for": "203.0.113.5, 127.0.0.1" },
     });
 
@@ -295,7 +681,7 @@ describe("isLoopbackPeer", () => {
   });
 
   test("falls back to peer IP when trustProxy is disabled", () => {
-    const req = new Request("http://localhost:7830/v1/browser-relay/token", {
+    const req = new Request("http://localhost:7830/v1/browser-relay", {
       headers: { "x-forwarded-for": "203.0.113.5, 127.0.0.1" },
     });
 

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

@@ -76,7 +76,7 @@ async function startGateway(): Promise<void> {
     stdio: ["ignore", "pipe", "pipe"],
   });
 
-  const deadline = Date.now() + 10_000;
+  const deadline = Date.now() + 30_000;
   while (Date.now() < deadline) {
     try {
       const res = await fetch(`http://localhost:${gatewayPort}/healthz`);
@@ -86,7 +86,7 @@ async function startGateway(): Promise<void> {
     }
     await new Promise((resolve) => setTimeout(resolve, 100));
   }
-  throw new Error("Gateway failed to start within 10 seconds");
+  throw new Error("Gateway failed to start within 30 seconds");
 }
 
 function startFakeCes(opts: {
@@ -176,7 +176,7 @@ describe("gateway managed credential bootstrap retry", () => {
     }
 
     expect(status).toBe(401);
-  }, 20_000);
+  }, 45_000);
 
   test("keeps retrying until configured credential reads succeed after CES list is already available", async () => {
     mkdirSync(testDir, { recursive: true });
@@ -220,7 +220,7 @@ describe("gateway managed credential bootstrap retry", () => {
     }
 
     expect(status).toBe(401);
-  }, 20_000);
+  }, 45_000);
 
   test("detects new Slack credentials when metadata is written after startup with no initial channel services", async () => {
     // Start with NO channel service metadata — only non-channel credentials
@@ -274,5 +274,5 @@ describe("gateway managed credential bootstrap retry", () => {
     }
 
     expect(status).toBe(401);
-  }, 20_000);
+  }, 45_000);
 });

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

@@ -97,7 +97,7 @@ const {
 } = await import("../feature-flag-defaults.js");
 const { clearFeatureFlagStoreCache, readPersistedFeatureFlags } =
   await import("../feature-flag-store.js");
-const { clearRemoteFeatureFlagStoreCache } =
+const { clearRemoteFeatureFlagStoreCache, writeRemoteFeatureFlags } =
   await import("../feature-flag-remote-store.js");
 
 describe("GET /v1/feature-flags handler", () => {
@@ -337,6 +337,43 @@ describe("GET /v1/feature-flags handler", () => {
     expect(emailFlag.enabled).toBe(false);
   });
 
+  test("reflects updated flags after remote sync writes new values (stale cache regression)", async () => {
+    // Scenario: the LD poller (RemoteFeatureFlagSync) writes
+    // email-channel: false, the gateway caches it, then a subsequent
+    // poll writes email-channel: true. The GET handler should return
+    // the updated value because writeRemoteFeatureFlags() updates
+    // both disk and the in-memory cache.
+
+    // Step 1: First poll writes email-channel: false (simulated via
+    // writeRemoteFeatureFlags, which is what the poller calls internally).
+    writeRemoteFeatureFlags({ "email-channel": false });
+
+    const handler = createFeatureFlagsGetHandler();
+    const res1 = await handler(
+      new Request("http://gateway.test/v1/feature-flags"),
+    );
+    const body1 = await res1.json();
+    const emailFlag1 = body1.flags.find(
+      (f: { key: string }) => f.key === "email-channel",
+    );
+    expect(emailFlag1.enabled).toBe(false);
+
+    // Step 2: Second poll writes email-channel: true — the poller
+    // calls writeRemoteFeatureFlags which updates file + cache.
+    writeRemoteFeatureFlags({ "email-channel": true });
+
+    // Step 3: The GET handler should immediately reflect the update
+    // without needing a file-watcher round-trip.
+    const res2 = await handler(
+      new Request("http://gateway.test/v1/feature-flags"),
+    );
+    const body2 = await res2.json();
+    const emailFlag2 = body2.flags.find(
+      (f: { key: string }) => f.key === "email-channel",
+    );
+    expect(emailFlag2.enabled).toBe(true);
+  });
+
   test("registry default used when neither local nor remote is set", async () => {
     // No local override
     if (existsSync(featureFlagStorePath)) {