@vellumai/vellum-gateway 0.3.16 → 0.3.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/vellum-gateway",
-  "version": "0.3.16",
+  "version": "0.3.18",
   "type": "module",
   "scripts": {
     "dev": "bun run --watch src/index.ts",

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

@@ -0,0 +1,257 @@
+import { describe, test, expect, mock, beforeEach, afterAll } from "bun:test";
+import type { GatewayConfig } from "../config.js";
+import {
+  createBrowserRelayWebsocketHandler,
+  getBrowserRelayWebsocketHandlers,
+} from "../http/routes/browser-relay-websocket.js";
+
+const WS_CONNECTING = WebSocket.CONNECTING; // 0
+const WS_OPEN = WebSocket.OPEN; // 1
+const WS_CLOSED = WebSocket.CLOSED; // 3
+
+function makeConfig(overrides: Partial<GatewayConfig> = {}): GatewayConfig {
+  const merged: GatewayConfig = {
+    telegramBotToken: "tok",
+    telegramWebhookSecret: "wh-ver",
+    telegramApiBaseUrl: "https://api.telegram.org",
+    assistantRuntimeBaseUrl: "http://localhost:7821",
+    routingEntries: [],
+    defaultAssistantId: undefined,
+    unmappedPolicy: "reject",
+    port: 7830,
+    runtimeBearerToken: undefined,
+    runtimeGatewayOriginSecret: undefined,
+    runtimeProxyEnabled: false,
+    runtimeProxyRequireAuth: true,
+    runtimeProxyBearerToken: undefined,
+    shutdownDrainMs: 5000,
+    runtimeTimeoutMs: 30000,
+    runtimeMaxRetries: 2,
+    runtimeInitialBackoffMs: 500,
+    telegramDeliverAuthBypass: false,
+    telegramInitialBackoffMs: 1000,
+    telegramMaxRetries: 3,
+    telegramTimeoutMs: 15000,
+    maxWebhookPayloadBytes: 1048576,
+    logFile: { dir: undefined, retentionDays: 30 },
+    maxAttachmentBytes: 20971520,
+    maxAttachmentConcurrency: 3,
+    twilioAuthToken: undefined,
+    twilioAccountSid: undefined,
+    twilioPhoneNumber: undefined,
+    smsDeliverAuthBypass: false,
+    ingressPublicBaseUrl: undefined,
+    gatewayInternalBaseUrl: "http://127.0.0.1:7830",
+    whatsappPhoneNumberId: undefined,
+    whatsappAccessToken: undefined,
+    whatsappAppSecret: undefined,
+    whatsappWebhookVerifyToken: undefined,
+    whatsappDeliverAuthBypass: false,
+    whatsappTimeoutMs: 15000,
+    whatsappMaxRetries: 3,
+    whatsappInitialBackoffMs: 1000,
+    slackChannelBotToken: undefined,
+    slackChannelAppToken: undefined,
+    slackDeliverAuthBypass: false,
+    trustProxy: false,
+    ...overrides,
+  };
+  if (merged.runtimeGatewayOriginSecret === undefined) {
+    merged.runtimeGatewayOriginSecret = merged.runtimeBearerToken;
+  }
+  return merged;
+}
+
+function createFakeDownstreamWs(data: Record<string, unknown> = {}) {
+  const sent: (string | Uint8Array)[] = [];
+  const closes: { code: number; reason: string }[] = [];
+  return {
+    data,
+    sent,
+    closes,
+    send: mock((msg: string | Uint8Array) => {
+      sent.push(msg);
+    }),
+    close: mock((code?: number, reason?: string) => {
+      closes.push({ code: code ?? 1000, reason: reason ?? "" });
+    }),
+  };
+}
+
+function createFakeUpstreamWs() {
+  const listeners: Record<string, ((...args: unknown[]) => void)[]> = {};
+  const sent: unknown[] = [];
+  return {
+    readyState: WS_CONNECTING as number,
+    sent,
+    listeners,
+    addEventListener: mock((event: string, cb: (...args: unknown[]) => void) => {
+      (listeners[event] ??= []).push(cb);
+    }),
+    send: mock((msg: unknown) => {
+      sent.push(msg);
+    }),
+    close: mock(() => {}),
+    emit(event: string, detail: unknown = {}) {
+      for (const cb of listeners[event] ?? []) {
+        cb(detail);
+      }
+    },
+  };
+}
+
+describe("createBrowserRelayWebsocketHandler", () => {
+  const TEST_TOKEN = "relay-token-abc123";
+
+  test("upgrades when token query parameter is valid", () => {
+    const config = makeConfig({ runtimeProxyBearerToken: TEST_TOKEN });
+    const handler = createBrowserRelayWebsocketHandler(config);
+    const req = new Request(
+      `http://localhost:7830/v1/browser-relay?token=${TEST_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).toBeUndefined();
+    expect(fakeServer.upgrade).toHaveBeenCalledTimes(1);
+  });
+
+  test("returns 401 when token is missing", () => {
+    const config = makeConfig({ runtimeProxyBearerToken: TEST_TOKEN });
+    const handler = createBrowserRelayWebsocketHandler(config);
+    const req = new Request("http://localhost:7830/v1/browser-relay", {
+      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();
+  });
+
+  test("allows unauthenticated upgrade when runtime proxy auth is disabled", () => {
+    const config = makeConfig({ runtimeProxyRequireAuth: false, runtimeProxyBearerToken: undefined });
+    const handler = createBrowserRelayWebsocketHandler(config);
+    const req = new Request("http://localhost:7830/v1/browser-relay", {
+      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).toBeUndefined();
+    expect(fakeServer.upgrade).toHaveBeenCalledTimes(1);
+  });
+
+  test("returns 403 when non-loopback host is requested from a public peer", () => {
+    const config = makeConfig({ runtimeProxyBearerToken: TEST_TOKEN });
+    const handler = createBrowserRelayWebsocketHandler(config);
+    const req = new Request(
+      `http://gateway.example.com:7830/v1/browser-relay?token=${TEST_TOKEN}`,
+      { headers: { upgrade: "websocket" } },
+    );
+    const fakeServer = {
+      requestIP: mock(() => ({ address: "8.8.8.8", 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(403);
+    expect(fakeServer.upgrade).not.toHaveBeenCalled();
+  });
+
+  test("returns 403 for localhost host when peer is public (host spoof prevention)", () => {
+    const config = makeConfig({ runtimeProxyBearerToken: TEST_TOKEN });
+    const handler = createBrowserRelayWebsocketHandler(config);
+    const req = new Request(
+      `http://localhost:7830/v1/browser-relay?token=${TEST_TOKEN}`,
+      { headers: { upgrade: "websocket" } },
+    );
+    const fakeServer = {
+      requestIP: mock(() => ({ address: "8.8.8.8", 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(403);
+    expect(fakeServer.upgrade).not.toHaveBeenCalled();
+  });
+
+  test("allows non-loopback host when peer is private network", () => {
+    const config = makeConfig({ runtimeProxyBearerToken: TEST_TOKEN });
+    const handler = createBrowserRelayWebsocketHandler(config);
+    const req = new Request(
+      `http://gateway.example.com:7830/v1/browser-relay?token=${TEST_TOKEN}`,
+      { headers: { upgrade: "websocket" } },
+    );
+    const fakeServer = {
+      requestIP: mock(() => ({ address: "10.42.0.8", family: "IPv4", port: 54000 })),
+      upgrade: mock(() => true),
+    } as unknown as import("bun").Server<any>;
+
+    const res = handler(req, fakeServer);
+
+    expect(res).toBeUndefined();
+    expect(fakeServer.upgrade).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("getBrowserRelayWebsocketHandlers", () => {
+  const OriginalWebSocket = globalThis.WebSocket;
+  let fakeUpstream: ReturnType<typeof createFakeUpstreamWs>;
+  let handlers: ReturnType<typeof getBrowserRelayWebsocketHandlers>;
+
+  beforeEach(() => {
+    fakeUpstream = createFakeUpstreamWs();
+    const MockWS = mock(() => fakeUpstream);
+    Object.assign(MockWS, {
+      CONNECTING: WS_CONNECTING,
+      OPEN: WS_OPEN,
+      CLOSING: 2,
+      CLOSED: WS_CLOSED,
+    });
+    globalThis.WebSocket = MockWS as unknown as typeof WebSocket;
+    handlers = getBrowserRelayWebsocketHandlers();
+  });
+
+  afterAll(() => {
+    globalThis.WebSocket = OriginalWebSocket;
+  });
+
+  test("open targets runtime browser-relay websocket and flushes buffered messages", () => {
+    const ws = createFakeDownstreamWs({
+      wsType: "browser-relay",
+      config: makeConfig({
+        assistantRuntimeBaseUrl: "http://runtime.internal:7821",
+        runtimeBearerToken: "runtime-token",
+      }),
+    });
+
+    handlers.open(ws as never);
+    handlers.message(ws as never, "hello-before-open");
+
+    const MockWS = globalThis.WebSocket as unknown as ReturnType<typeof mock>;
+    expect(MockWS).toHaveBeenCalledWith("ws://runtime.internal:7821/v1/browser-relay?token=runtime-token");
+
+    fakeUpstream.readyState = WS_OPEN;
+    fakeUpstream.emit("open");
+    expect(fakeUpstream.sent).toEqual(["hello-before-open"]);
+
+    fakeUpstream.emit("message", { data: "runtime-message" });
+    expect(ws.sent).toEqual(["runtime-message"]);
+  });
+});

package/src/__tests__/load-guards.test.ts

@@ -43,6 +43,9 @@ function makeConfig(overrides: Partial<GatewayConfig> = {}): GatewayConfig {
     whatsappTimeoutMs: 15000,
     whatsappMaxRetries: 3,
     whatsappInitialBackoffMs: 1000,
+    slackChannelBotToken: undefined,
+    slackChannelAppToken: undefined,
+    slackDeliverAuthBypass: false,
     trustProxy: false,
     ...overrides,
   };

package/src/__tests__/oauth-callback.test.ts

@@ -55,6 +55,9 @@ function makeConfig(overrides: Partial<GatewayConfig> = {}): GatewayConfig {
     whatsappTimeoutMs: 15000,
     whatsappMaxRetries: 3,
     whatsappInitialBackoffMs: 1000,
+    slackChannelBotToken: undefined,
+    slackChannelAppToken: undefined,
+    slackDeliverAuthBypass: false,
     trustProxy: false,
     ...overrides,
   };

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

@@ -43,6 +43,9 @@ function makeConfig(overrides: Partial<GatewayConfig> = {}): GatewayConfig {
     whatsappTimeoutMs: 15000,
     whatsappMaxRetries: 3,
     whatsappInitialBackoffMs: 1000,
+    slackChannelBotToken: undefined,
+    slackChannelAppToken: undefined,
+    slackDeliverAuthBypass: false,
     trustProxy: false,
     ...overrides,
   };

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

@@ -58,6 +58,9 @@ function makeConfig(overrides: Partial<GatewayConfig> = {}): GatewayConfig {
     whatsappTimeoutMs: 15000,
     whatsappMaxRetries: 3,
     whatsappInitialBackoffMs: 1000,
+    slackChannelBotToken: undefined,
+    slackChannelAppToken: undefined,
+    slackDeliverAuthBypass: false,
     trustProxy: false,
     ...overrides,
   };

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

@@ -53,6 +53,9 @@ function makeConfig(overrides: Partial<GatewayConfig> = {}): GatewayConfig {
     whatsappTimeoutMs: 15000,
     whatsappMaxRetries: 3,
     whatsappInitialBackoffMs: 1000,
+    slackChannelBotToken: undefined,
+    slackChannelAppToken: undefined,
+    slackDeliverAuthBypass: false,
     trustProxy: false,
     ...overrides,
   };

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

@@ -51,6 +51,9 @@ function makeConfig(overrides: Partial<GatewayConfig> = {}): GatewayConfig {
     whatsappTimeoutMs: 15000,
     whatsappMaxRetries: 3,
     whatsappInitialBackoffMs: 1000,
+    slackChannelBotToken: undefined,
+    slackChannelAppToken: undefined,
+    slackDeliverAuthBypass: false,
     trustProxy: false,
     ...overrides,
   };

package/src/__tests__/sms-ingress-guard.test.ts

@@ -57,6 +57,9 @@ function makeConfig(overrides: Partial<GatewayConfig> = {}): GatewayConfig {
     whatsappTimeoutMs: 15000,
     whatsappMaxRetries: 3,
     whatsappInitialBackoffMs: 1000,
+    slackChannelBotToken: undefined,
+    slackChannelAppToken: undefined,
+    slackDeliverAuthBypass: false,
     trustProxy: false,
     ...overrides,
   };

package/src/__tests__/telegram-api-redaction.test.ts

@@ -51,6 +51,9 @@ function makeConfig(overrides: Partial<GatewayConfig> = {}): GatewayConfig {
     whatsappTimeoutMs: 15000,
     whatsappMaxRetries: 3,
     whatsappInitialBackoffMs: 1000,
+    slackChannelBotToken: undefined,
+    slackChannelAppToken: undefined,
+    slackDeliverAuthBypass: false,
     trustProxy: false,
     ...overrides,
   };

package/src/__tests__/telegram-deliver-auth.test.ts

@@ -53,6 +53,9 @@ function makeConfig(overrides: Partial<GatewayConfig> = {}): GatewayConfig {
     whatsappTimeoutMs: 15000,
     whatsappMaxRetries: 3,
     whatsappInitialBackoffMs: 1000,
+    slackChannelBotToken: undefined,
+    slackChannelAppToken: undefined,
+    slackDeliverAuthBypass: false,
     trustProxy: false,
     ...overrides,
   };

package/src/__tests__/telegram-reconcile-route.test.ts

@@ -58,6 +58,9 @@ function makeConfig(overrides: Partial<GatewayConfig> = {}): GatewayConfig {
     whatsappTimeoutMs: 15000,
     whatsappMaxRetries: 3,
     whatsappInitialBackoffMs: 1000,
+    slackChannelBotToken: undefined,
+    slackChannelAppToken: undefined,
+    slackDeliverAuthBypass: false,
     trustProxy: false,
     ...overrides,
   };

package/src/__tests__/telegram-send-attachments.test.ts

@@ -52,6 +52,9 @@ function makeConfig(overrides: Partial<GatewayConfig> = {}): GatewayConfig {
     whatsappTimeoutMs: 15000,
     whatsappMaxRetries: 3,
     whatsappInitialBackoffMs: 1000,
+    slackChannelBotToken: undefined,
+    slackChannelAppToken: undefined,
+    slackDeliverAuthBypass: false,
     trustProxy: false,
     ...overrides,
   };

package/src/__tests__/telegram-webhook-handler.test.ts

@@ -51,6 +51,9 @@ function makeConfig(overrides: Partial<GatewayConfig> = {}): GatewayConfig {
     whatsappTimeoutMs: 15000,
     whatsappMaxRetries: 3,
     whatsappInitialBackoffMs: 1000,
+    slackChannelBotToken: undefined,
+    slackChannelAppToken: undefined,
+    slackDeliverAuthBypass: false,
     trustProxy: false,
     ...overrides,
   };

package/src/__tests__/telegram-webhook-manager.test.ts

@@ -51,6 +51,9 @@ function makeConfig(overrides: Partial<GatewayConfig> = {}): GatewayConfig {
     whatsappTimeoutMs: 15000,
     whatsappMaxRetries: 3,
     whatsappInitialBackoffMs: 1000,
+    slackChannelBotToken: undefined,
+    slackChannelAppToken: undefined,
+    slackDeliverAuthBypass: false,
     trustProxy: false,
     ...overrides,
   };

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

@@ -58,6 +58,9 @@ function makeConfig(overrides: Partial<GatewayConfig> = {}): GatewayConfig {
     whatsappTimeoutMs: 15000,
     whatsappMaxRetries: 3,
     whatsappInitialBackoffMs: 1000,
+    slackChannelBotToken: undefined,
+    slackChannelAppToken: undefined,
+    slackDeliverAuthBypass: false,
     trustProxy: false,
     ...overrides,
   };

package/src/__tests__/twilio-webhooks.test.ts

@@ -56,6 +56,9 @@ function makeConfig(overrides: Partial<GatewayConfig> = {}): GatewayConfig {
     whatsappTimeoutMs: 15000,
     whatsappMaxRetries: 3,
     whatsappInitialBackoffMs: 1000,
+    slackChannelBotToken: undefined,
+    slackChannelAppToken: undefined,
+    slackDeliverAuthBypass: false,
     trustProxy: false,
     ...overrides,
   };

package/src/http/routes/browser-relay-websocket.ts

@@ -0,0 +1,195 @@
+import type { GatewayConfig } from "../../config.js";
+import { getLogger } from "../../logger.js";
+import { validateBearerToken } from "../auth/bearer.js";
+
+const log = getLogger("browser-relay-ws");
+
+// Cap buffered messages to prevent unbounded memory growth if upstream stalls
+const MAX_PENDING_MESSAGES = 100;
+
+function isPrivateAddress(addr: string): boolean {
+  const v4Mapped = addr.match(/^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/i);
+  const normalized = v4Mapped ? v4Mapped[1] : addr;
+
+  if (normalized.includes(".")) {
+    const parts = normalized.split(".").map(Number);
+    if (parts.length !== 4 || parts.some((p) => Number.isNaN(p) || p < 0 || p > 255)) return false;
+
+    if (parts[0] === 127) return true;
+    if (parts[0] === 10) return true;
+    if (parts[0] === 172 && parts[1] >= 16 && parts[1] <= 31) return true;
+    if (parts[0] === 192 && parts[1] === 168) return true;
+    if (parts[0] === 169 && parts[1] === 254) return true;
+
+    return false;
+  }
+
+  const lower = normalized.toLowerCase();
+  if (lower === "::1") return true;
+  if (lower.startsWith("fc") || lower.startsWith("fd")) return true;
+  if (lower.startsWith("fe80")) return true;
+
+  return false;
+}
+
+function isPrivateNetworkPeer(server: import("bun").Server<unknown>, req: Request): boolean {
+  const ip = server.requestIP(req);
+  if (!ip) return false;
+  return isPrivateAddress(ip.address);
+}
+
+export type BrowserRelaySocketData = {
+  wsType: "browser-relay";
+  config: GatewayConfig;
+  clientToken?: string;
+  upstream?: WebSocket;
+  pendingMessages?: (string | ArrayBuffer | Uint8Array)[];
+};
+
+/**
+ * Create a WebSocket upgrade handler that proxies browser-relay frames between
+ * the local Chrome extension and the runtime's /v1/browser-relay endpoint.
+ */
+export function createBrowserRelayWebsocketHandler(config: GatewayConfig) {
+  return function handleUpgrade(
+    req: Request,
+    server: import("bun").Server<unknown>,
+  ): Response | undefined {
+    if (req.headers.get("upgrade")?.toLowerCase() !== "websocket") {
+      return new Response("Upgrade Required", { status: 426 });
+    }
+
+    const url = new URL(req.url);
+
+    // Trust actual peer IP, not request host headers, for local/private gating.
+    if (!isPrivateNetworkPeer(server, req)) {
+      return new Response("Browser relay only accepts connections from localhost", { status: 403 });
+    }
+
+    const authResponse = checkBrowserRelayAuth(req, url, config);
+    if (authResponse) return authResponse;
+
+    const upgraded = server.upgrade(req, {
+      data: {
+        wsType: "browser-relay",
+        config,
+        clientToken: url.searchParams.get("token") ?? undefined,
+      },
+    });
+
+    if (!upgraded) {
+      return new Response("WebSocket upgrade failed", { status: 500 });
+    }
+
+    // Return undefined to indicate upgrade was handled
+    return undefined;
+  };
+}
+
+function checkBrowserRelayAuth(
+  req: Request,
+  url: URL,
+  config: GatewayConfig,
+): Response | null {
+  if (!config.runtimeProxyRequireAuth) return null;
+
+  if (!config.runtimeProxyBearerToken) {
+    log.error("Browser relay WS: no bearer token configured — rejecting (fail-closed)");
+    return new Response("Service not configured: bearer token required", { status: 503 });
+  }
+
+  const authHeader = req.headers.get("authorization");
+  const queryToken = url.searchParams.get("token");
+  const tokenSource = authHeader ?? (queryToken ? `Bearer ${queryToken}` : null);
+
+  const result = validateBearerToken(tokenSource, config.runtimeProxyBearerToken);
+  if (!result.authorized) {
+    log.warn({ reason: result.reason }, "Browser relay WS: authentication failed");
+    return new Response("Unauthorized", { status: 401 });
+  }
+
+  return null;
+}
+
+/**
+ * WebSocket handler config for Bun.serve() that proxies frames to runtime.
+ */
+export function getBrowserRelayWebsocketHandlers() {
+  return {
+    open(ws: import("bun").ServerWebSocket<BrowserRelaySocketData>) {
+      const { config } = ws.data;
+
+      // Initialize message buffer for frames arriving before upstream connects
+      ws.data.pendingMessages = [];
+
+      const runtimeBase = config.assistantRuntimeBaseUrl.replace(/^http/, "ws");
+      const upstreamToken = config.runtimeBearerToken || config.runtimeProxyBearerToken || ws.data.clientToken;
+      const query = upstreamToken ? `?token=${encodeURIComponent(upstreamToken)}` : "";
+      const upstreamUrl = `${runtimeBase}/v1/browser-relay${query}`;
+      const logSafeUpstreamUrl = `${runtimeBase}/v1/browser-relay${upstreamToken ? "?token=<redacted>" : ""}`;
+
+      log.info({ upstreamUrl: logSafeUpstreamUrl }, "Opening upstream browser relay WS to runtime");
+
+      const upstream = new WebSocket(upstreamUrl);
+      ws.data.upstream = upstream;
+
+      upstream.addEventListener("open", () => {
+        log.info("Upstream browser relay WS connected");
+        const pending = ws.data.pendingMessages;
+        if (pending) {
+          for (const msg of pending) {
+            upstream.send(msg);
+          }
+          ws.data.pendingMessages = undefined;
+        }
+      });
+
+      upstream.addEventListener("message", (event) => {
+        const data = typeof event.data === "string"
+          ? event.data
+          : new Uint8Array(event.data as ArrayBuffer);
+        ws.send(data);
+      });
+
+      upstream.addEventListener("close", (event) => {
+        log.info({ code: event.code }, "Upstream browser relay WS closed");
+        ws.close(event.code, event.reason);
+      });
+
+      upstream.addEventListener("error", (event) => {
+        log.error({ error: event }, "Upstream browser relay WS error");
+        ws.close(1011, "Upstream error");
+      });
+    },
+
+    message(
+      ws: import("bun").ServerWebSocket<BrowserRelaySocketData>,
+      message: string | ArrayBuffer | Uint8Array,
+    ) {
+      const upstream = ws.data.upstream;
+      if (upstream && upstream.readyState === WebSocket.OPEN) {
+        upstream.send(message);
+      } else if (ws.data.pendingMessages) {
+        if (ws.data.pendingMessages.length >= MAX_PENDING_MESSAGES) {
+          log.warn("Browser relay pending message buffer overflow — closing connection");
+          ws.close(1008, "Buffer overflow");
+          return;
+        }
+        ws.data.pendingMessages.push(message);
+      }
+    },
+
+    close(
+      ws: import("bun").ServerWebSocket<BrowserRelaySocketData>,
+      code: number,
+      reason: string,
+    ) {
+      const { upstream } = ws.data;
+      log.info({ code, reason }, "Browser relay downstream WS closed");
+      ws.data.pendingMessages = undefined;
+      if (upstream && (upstream.readyState === WebSocket.OPEN || upstream.readyState === WebSocket.CONNECTING)) {
+        upstream.close(code, reason);
+      }
+    },
+  };
+}

package/src/http/routes/slack-deliver.ts

@@ -39,7 +39,7 @@ export function createSlackDeliverHandler(config: GatewayConfig) {
     }
 
     if (typeof body !== 'object' || body === null) {
-      return Response.json({ ok: false, error: "Invalid request body" }, { status: 400 });
+      return Response.json({ error: "Invalid request body" }, { status: 400 });
     }
 
     if (body.attachments && Array.isArray(body.attachments) && body.attachments.length > 0) {

package/src/http/routes/sms-deliver.test.ts

@@ -55,6 +55,9 @@ function makeConfig(overrides: Partial<GatewayConfig> = {}): GatewayConfig {
     whatsappTimeoutMs: 15000,
     whatsappMaxRetries: 3,
     whatsappInitialBackoffMs: 1000,
+    slackChannelBotToken: undefined,
+    slackChannelAppToken: undefined,
+    slackDeliverAuthBypass: false,
     trustProxy: false,
     ...overrides,
   };

package/src/http/routes/telegram-deliver.test.ts

@@ -62,6 +62,9 @@ function makeConfig(overrides: Partial<GatewayConfig> = {}): GatewayConfig {
     whatsappTimeoutMs: 15000,
     whatsappMaxRetries: 3,
     whatsappInitialBackoffMs: 1000,
+    slackChannelBotToken: undefined,
+    slackChannelAppToken: undefined,
+    slackDeliverAuthBypass: false,
     trustProxy: false,
     ...overrides,
   };

package/src/http/routes/telegram-webhook.test.ts

@@ -89,6 +89,9 @@ const baseConfig: GatewayConfig = {
   whatsappTimeoutMs: 15000,
   whatsappMaxRetries: 3,
   whatsappInitialBackoffMs: 1000,
+    slackChannelBotToken: undefined,
+    slackChannelAppToken: undefined,
+    slackDeliverAuthBypass: false,
     trustProxy: false,
 };
 

package/src/http/routes/twilio-relay-websocket.ts

@@ -19,7 +19,7 @@ type RelaySocketData = {
  * frames between Twilio and the runtime's /v1/calls/relay endpoint.
  */
 export function createTwilioRelayWebsocketHandler(config: GatewayConfig) {
-  return function handleUpgrade(req: Request, server: import("bun").Server<RelaySocketData>): Response | undefined {
+  return function handleUpgrade(req: Request, server: import("bun").Server<unknown>): Response | undefined {
     const url = new URL(req.url);
     const callSessionId = url.searchParams.get("callSessionId");
 

package/src/http/routes/twilio-sms-webhook.test.ts

@@ -72,6 +72,9 @@ const baseConfig: GatewayConfig = {
   whatsappTimeoutMs: 15000,
   whatsappMaxRetries: 3,
   whatsappInitialBackoffMs: 1000,
+    slackChannelBotToken: undefined,
+    slackChannelAppToken: undefined,
+    slackDeliverAuthBypass: false,
     trustProxy: false,
 };
 

package/src/http/routes/twilio-voice-webhook.test.ts

@@ -105,6 +105,9 @@ const baseConfig: GatewayConfig = {
   whatsappTimeoutMs: 15000,
   whatsappMaxRetries: 3,
   whatsappInitialBackoffMs: 1000,
+    slackChannelBotToken: undefined,
+    slackChannelAppToken: undefined,
+    slackDeliverAuthBypass: false,
     trustProxy: false,
 };
 

package/src/http/routes/whatsapp-deliver.test.ts

@@ -59,6 +59,9 @@ function makeConfig(overrides: Partial<GatewayConfig> = {}): GatewayConfig {
     whatsappTimeoutMs: 15000,
     whatsappMaxRetries: 3,
     whatsappInitialBackoffMs: 1000,
+    slackChannelBotToken: undefined,
+    slackChannelAppToken: undefined,
+    slackDeliverAuthBypass: false,
     trustProxy: false,
     ...overrides,
   };

package/src/http/routes/whatsapp-webhook.test.ts

@@ -76,6 +76,9 @@ const baseConfig: GatewayConfig = {
   whatsappTimeoutMs: 15000,
   whatsappMaxRetries: 3,
   whatsappInitialBackoffMs: 1000,
+    slackChannelBotToken: undefined,
+    slackChannelAppToken: undefined,
+    slackDeliverAuthBypass: false,
     trustProxy: false,
 };
 

package/src/index.ts

@@ -7,6 +7,11 @@ import { ConfigFileWatcher } from "./config-file-watcher.js";
 import { loadConfig, isSlackChannelConfigured, type GatewayConfig } from "./config.js";
 import { CredentialWatcher } from "./credential-watcher.js";
 import { createRuntimeProxyHandler } from "./http/routes/runtime-proxy.js";
+import {
+  createBrowserRelayWebsocketHandler,
+  getBrowserRelayWebsocketHandlers,
+  type BrowserRelaySocketData,
+} from "./http/routes/browser-relay-websocket.js";
 import { createTelegramDeliverHandler } from "./http/routes/telegram-deliver.js";
 import { createTelegramReconcileHandler } from "./http/routes/telegram-reconcile.js";
 import { createTelegramWebhookHandler } from "./http/routes/telegram-webhook.js";
@@ -41,6 +46,10 @@ let draining = false;
 // Shared rate limiter for auth failures and unauthenticated endpoints
 const authRateLimiter = new AuthRateLimiter();
 
+function isBrowserRelaySocketData(data: unknown): data is BrowserRelaySocketData {
+  return !!data && typeof data === "object" && (data as { wsType?: unknown }).wsType === "browser-relay";
+}
+
 function getClientIp(req: Request, server: ReturnType<typeof Bun.serve>, trustProxy: boolean): string {
   if (trustProxy) {
     const forwarded = req.headers.get("x-forwarded-for");
@@ -126,6 +135,9 @@ function main() {
   const handleTwilioStatusWebhook = createTwilioStatusWebhookHandler(config);
   const handleTwilioConnectActionWebhook = createTwilioConnectActionWebhookHandler(config);
   const handleTwilioRelayWs = createTwilioRelayWebsocketHandler(config);
+  const handleBrowserRelayWs = createBrowserRelayWebsocketHandler(config);
+  const twilioRelayWebsocketHandlers = getRelayWebsocketHandlers();
+  const browserRelayWebsocketHandlers = getBrowserRelayWebsocketHandlers();
   const { handler: handleTwilioSmsWebhook, dedupCache: smsDedupCache } = createTwilioSmsWebhookHandler(config);
   const handleSmsDeliver = createSmsDeliverHandler(config);
   const { handler: handleWhatsAppWebhook, dedupCache: whatsappDedupCache } = createWhatsAppWebhookHandler(config);
@@ -140,7 +152,29 @@ function main() {
 
   const server = Bun.serve({
     port: config.port,
-    websocket: getRelayWebsocketHandlers(),
+    websocket: {
+      open(ws) {
+        if (isBrowserRelaySocketData(ws.data)) {
+          browserRelayWebsocketHandlers.open(ws as never);
+          return;
+        }
+        twilioRelayWebsocketHandlers.open(ws as never);
+      },
+      message(ws, message) {
+        if (isBrowserRelaySocketData(ws.data)) {
+          browserRelayWebsocketHandlers.message(ws as never, message);
+          return;
+        }
+        twilioRelayWebsocketHandlers.message(ws as never, message);
+      },
+      close(ws, code, reason) {
+        if (isBrowserRelaySocketData(ws.data)) {
+          browserRelayWebsocketHandlers.close(ws as never, code, reason);
+          return;
+        }
+        twilioRelayWebsocketHandlers.close(ws as never, code, reason);
+      },
+    },
     error(err) {
       if (err instanceof CircuitBreakerOpenError) {
         return Response.json(
@@ -183,6 +217,7 @@ function main() {
           url.pathname !== "/v1/calls/twilio/voice-webhook" &&
           url.pathname !== "/v1/calls/twilio/status" &&
           url.pathname !== "/v1/calls/twilio/connect-action" &&
+          url.pathname !== "/v1/browser-relay" &&
           url.pathname !== "/v1/calls/relay");
       if (isRateLimitedRoute) {
         const clientIp = getClientIp(req, svr, config.trustProxy);
@@ -308,6 +343,13 @@ function main() {
         return undefined as unknown as Response;
       }
 
+      if (config.runtimeProxyEnabled && url.pathname === "/v1/browser-relay") {
+        const upgradeResult = handleBrowserRelayWs(req, server);
+        if (upgradeResult !== undefined) return upgradeResult;
+        // If upgrade was handled, Bun doesn't need a response
+        return undefined as unknown as Response;
+      }
+
       if (url.pathname === "/webhooks/oauth/callback" && tracedReq.method === "GET") {
         const res = await handleOAuthCallback(tracedReq);
         if (res.status === 400) {

package/src/telegram/send.test.ts

@@ -54,6 +54,9 @@ const baseConfig: GatewayConfig = {
   whatsappTimeoutMs: 15000,
   whatsappMaxRetries: 3,
   whatsappInitialBackoffMs: 1000,
+    slackChannelBotToken: undefined,
+    slackChannelAppToken: undefined,
+    slackDeliverAuthBypass: false,
     trustProxy: false,
 };