@vellumai/vellum-gateway 0.7.0 → 0.7.2

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

@@ -1,381 +0,0 @@
-import { buildWsUpstreamUrl } from "@vellumai/assistant-client";
-
-import {
-  validateEdgeToken,
-  mintServiceToken,
-} from "../../auth/token-exchange.js";
-import { parseSub } from "../../auth/subject.js";
-import type { GatewayConfig } from "../../config.js";
-import { getLogger } from "../../logger.js";
-import { isLoopbackAddress } from "../../util/is-loopback-address.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 function isLoopbackPeer(
-  server: import("bun").Server<unknown>,
-  req: Request,
-  opts?: { trustProxy?: boolean },
-): boolean {
-  if (opts?.trustProxy) {
-    const forwarded = req.headers.get("x-forwarded-for");
-    if (forwarded) {
-      const first = forwarded.split(",")[0]?.trim();
-      if (!first) return false;
-      return isLoopbackAddress(first);
-    }
-  }
-
-  const peer = server.requestIP(req);
-  if (!peer) return false;
-  return isLoopbackAddress(peer.address);
-}
-
-/**
- * Resolved auth context carried into the upstream WS open handler.
- *
- * `guardianId` is populated whenever the downstream edge token carries an
- * actor principal (i.e. the sub is `actor:<assistantId>:<actorPrincipalId>`).
- * Service tokens — which intentionally do not carry a guardian — will have
- * `guardianId === undefined` and are expected to be rejected at upstream
- * upgrade time unless an alternate guardian-plumbing path is wired up.
- *
- * `clientInstanceId` is a stable per-extension-install identifier lifted
- * off the downstream handshake and forwarded to the runtime verbatim so
- * the multi-instance registry can key connections by (guardianId,
- * clientInstanceId). Without this forwarding, cloud reconnects from the
- * same extension install would each land in a fresh
- * `legacy:<connectionId>` slot and fail to supersede the prior socket.
- */
-export interface BrowserRelayAuthContext {
-  guardianId?: string;
-  /**
-   * Per-install identifier sourced from the downstream handshake — either
-   * the `clientInstanceId` query param (primary path, set by the Chrome
-   * extension via `buildUrl`) or the `x-client-instance-id` header.
-   * Propagated verbatim to the upstream runtime URL.
-   */
-  clientInstanceId?: string;
-  /** True when auth was checked and succeeded. */
-  authenticated: boolean;
-  /** True when runtime proxy auth is globally disabled (dev bypass). */
-  authBypassed: boolean;
-}
-
-export type BrowserRelaySocketData = {
-  wsType: "browser-relay";
-  config: GatewayConfig;
-  auth: BrowserRelayAuthContext;
-  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 authResult = checkBrowserRelayAuth(req, url, config);
-    if (!authResult.ok) return authResult.response;
-
-    const upgraded = server.upgrade(req, {
-      data: {
-        wsType: "browser-relay",
-        config,
-        auth: authResult.context,
-      },
-    });
-
-    if (!upgraded) {
-      return new Response("WebSocket upgrade failed", { status: 500 });
-    }
-
-    // Return undefined to indicate upgrade was handled
-    return undefined;
-  };
-}
-
-type AuthCheckResult =
-  | { ok: true; context: BrowserRelayAuthContext }
-  | { ok: false; response: Response };
-
-/**
- * Parse the downstream edge token and return a structured auth context.
- *
- * The gateway accepts the token via `Authorization: Bearer <jwt>` or a
- * `?token=` query parameter (browser WebSocket upgrades cannot set custom
- * headers, so the query param is the primary mechanism for the Chrome
- * extension). Tokens must carry an actor principal in `sub`; service
- * subjects (`svc:*:*`) are rejected on this route. The extracted
- * `actorPrincipalId` is propagated forward as the guardian identity so
- * the runtime can register the connection under the correct guardian.
- */
-export function checkBrowserRelayAuth(
-  req: Request,
-  url: URL,
-  config: GatewayConfig,
-): AuthCheckResult {
-  // Lift the per-install identifier off the downstream handshake so we
-  // can propagate it to the runtime regardless of the auth path below.
-  // The Chrome extension sets it as a query param via `buildUrl`; we
-  // also accept the `x-client-instance-id` header for parity with the
-  // runtime's own accepted forms. Empty strings are treated as absent
-  // so sparse clients don't all collapse into the same key.
-  const clientInstanceId = extractClientInstanceId(req, url);
-
-  if (!config.runtimeProxyRequireAuth) {
-    return {
-      ok: true,
-      context: {
-        authenticated: false,
-        authBypassed: true,
-        clientInstanceId,
-      },
-    };
-  }
-
-  const authHeader = req.headers.get("authorization");
-  const queryToken = url.searchParams.get("token");
-  const rawToken = authHeader
-    ? authHeader.toLowerCase().startsWith("bearer ")
-      ? authHeader.slice(7)
-      : null
-    : queryToken;
-
-  if (!rawToken) {
-    log.warn("Browser relay WS: no token provided");
-    return {
-      ok: false,
-      response: new Response("Unauthorized", { status: 401 }),
-    };
-  }
-
-  const result = validateEdgeToken(rawToken);
-  if (!result.ok) {
-    log.warn(
-      { reason: result.reason },
-      "Browser relay WS: authentication failed",
-    );
-    return {
-      ok: false,
-      response: new Response("Unauthorized", { status: 401 }),
-    };
-  }
-
-  const parsed = parseSub(result.claims.sub);
-  if (
-    !parsed.ok ||
-    parsed.principalType !== "actor" ||
-    !parsed.actorPrincipalId
-  ) {
-    // Fail closed: browser-relay sockets must be guardian-scoped.
-    // Service tokens (`svc:*:*`) do not carry an actor principal and are
-    // therefore rejected on this path.
-    log.warn(
-      {
-        reason: parsed.ok ? "missing_actor_principal" : parsed.reason,
-        sub: result.claims.sub,
-      },
-      "Browser relay WS: denied token without actor principal",
-    );
-    return {
-      ok: false,
-      response: new Response("Unauthorized", { status: 401 }),
-    };
-  }
-
-  return {
-    ok: true,
-    context: {
-      authenticated: true,
-      authBypassed: false,
-      guardianId: parsed.actorPrincipalId,
-      clientInstanceId,
-    },
-  };
-}
-
-/**
- * Extract the per-extension-install identifier from a downstream
- * browser-relay WS handshake. Query param is the primary path (the
- * Chrome extension sets it via `buildUrl` because WebSocket upgrades
- * cannot set custom headers from the browser); the header form is
- * accepted for completeness so non-browser clients have a consistent
- * contract. Empty strings are normalized to `undefined`.
- */
-function extractClientInstanceId(req: Request, url: URL): string | undefined {
-  const rawHeader = req.headers.get("x-client-instance-id")?.trim();
-  const rawQuery = url.searchParams.get("clientInstanceId")?.trim();
-  const picked = (rawHeader ?? "") || (rawQuery ?? "") || undefined;
-  return picked;
-}
-
-/**
- * WebSocket handler config for Bun.serve() that proxies frames to runtime.
- */
-export function getBrowserRelayWebsocketHandlers() {
-  return {
-    open(ws: import("bun").ServerWebSocket<BrowserRelaySocketData>) {
-      const { config, auth } = ws.data;
-
-      // Initialize message buffer for frames arriving before upstream connects
-      ws.data.pendingMessages = [];
-
-      // Build upstream URL with service-token auth and optional guardian/
-      // client-instance identifiers. The per-install identifier is forwarded
-      // so the runtime's multi-instance registry can key connections by
-      // (guardianId, clientInstanceId). Without this, cloud reconnects from
-      // the same extension install would each fall through to a fresh
-      // `legacy:<connectionId>` key and fail to supersede the prior socket.
-      const extraParams: Record<string, string> = {};
-      if (auth.guardianId) {
-        extraParams.guardianId = auth.guardianId;
-      }
-      if (auth.clientInstanceId) {
-        extraParams.clientInstanceId = auth.clientInstanceId;
-      }
-      const { url: upstreamUrl, logSafeUrl: logSafeUpstreamUrl } =
-        buildWsUpstreamUrl({
-          baseUrl: config.assistantRuntimeBaseUrl,
-          path: "/v1/browser-relay",
-          serviceToken: mintServiceToken(),
-          extraParams,
-        });
-
-      log.info(
-        {
-          upstreamUrl: logSafeUpstreamUrl,
-          guardianId: auth.guardianId,
-          clientInstanceId: auth.clientInstanceId,
-        },
-        "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/config-file-utils.ts

@@ -1,73 +0,0 @@
-import {
-  readFileSync,
-  writeFileSync,
-  mkdirSync,
-  existsSync,
-  renameSync,
-} from "node:fs";
-import { join, dirname } from "node:path";
-import { randomBytes } from "node:crypto";
-import { getWorkspaceDir } from "../../credential-reader.js";
-
-/**
- * Serializes config writes so concurrent PATCH requests don't race on
- * read-modify-write. Each write awaits the previous one before proceeding.
- *
- * This chain is shared across all config mutation routes (feature flags,
- * privacy config, etc.) to prevent concurrent writes to the same
- * config.json from overwriting each other's changes.
- */
-let configWriteChain: Promise<void> = Promise.resolve();
-
-/**
- * Enqueue a write operation onto the shared config write chain.
- * The callback runs only after all previously enqueued writes have finished.
- */
-export function enqueueConfigWrite(fn: () => void): void {
-  configWriteChain = configWriteChain.then(fn);
-}
-
-export function getConfigPath(): string {
-  return join(getWorkspaceDir(), "config.json");
-}
-
-export type ConfigReadResult =
-  | { ok: true; data: Record<string, unknown> }
-  | { ok: false; reason: "malformed"; detail: string };
-
-export function readConfigFile(): ConfigReadResult {
-  const cfgPath = getConfigPath();
-  if (!existsSync(cfgPath)) {
-    return { ok: true, data: {} };
-  }
-  try {
-    const raw = readFileSync(cfgPath, "utf-8");
-    const parsed = JSON.parse(raw);
-    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-      return {
-        ok: false,
-        reason: "malformed",
-        detail: "Config file is not a JSON object",
-      };
-    }
-    return { ok: true, data: parsed };
-  } catch (err) {
-    return { ok: false, reason: "malformed", detail: String(err) };
-  }
-}
-
-/**
- * Atomically write the config file: write to a temporary file in the same
- * directory, then rename. This avoids partial-file corruption if the process
- * crashes mid-write.
- */
-export function writeConfigFileAtomic(data: Record<string, unknown>): void {
-  const cfgPath = getConfigPath();
-  const dir = dirname(cfgPath);
-  if (!existsSync(dir)) {
-    mkdirSync(dir, { recursive: true });
-  }
-  const tmpPath = join(dir, `.config.${randomBytes(6).toString("hex")}.tmp`);
-  writeFileSync(tmpPath, JSON.stringify(data, null, 2) + "\n", "utf-8");
-  renameSync(tmpPath, cfgPath);
-}

package/src/ipc/capability-token-handlers.ts

@@ -1,30 +0,0 @@
-/**
- * IPC route definitions for capability token operations.
- *
- * Exposes token verification to the assistant daemon so it can
- * authenticate browser-relay WebSocket handshakes without reading
- * the HMAC secret directly from the filesystem.
- */
-
-import { z } from "zod";
-
-import { verifyHostBrowserCapability } from "../auth/capability-tokens.js";
-import type { IpcRoute } from "./server.js";
-
-const VerifyCapabilityTokenParamsSchema = z.object({
-  token: z.string(),
-});
-
-export const capabilityTokenRoutes: IpcRoute[] = [
-  {
-    method: "verify_capability_token",
-    schema: VerifyCapabilityTokenParamsSchema,
-    handler: (params) => {
-      const { token } = params as z.infer<
-        typeof VerifyCapabilityTokenParamsSchema
-      >;
-      const claims = verifyHostBrowserCapability(token);
-      return claims ?? { valid: false };
-    },
-  },
-];

package/src/pairing/approved-devices-store.ts

@@ -1,110 +0,0 @@
-/**
- * Persistent store for always-allowed paired devices.
- *
- * Persisted to $GATEWAY_SECURITY_DIR/approved-devices.json using an
- * atomic-write pattern (write .tmp → rename → chmod).
- */
-
-import { createHash } from "node:crypto";
-import {
-  chmodSync,
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  renameSync,
-  writeFileSync,
-} from "node:fs";
-import { dirname, join } from "node:path";
-
-import { getLogger } from "../logger.js";
-import { getGatewaySecurityDir } from "../paths.js";
-
-const log = getLogger("approved-devices-store");
-
-export interface ApprovedDevice {
-  hashedDeviceId: string;
-  deviceName: string;
-  lastPairedAt: number;
-}
-
-interface ApprovedDevicesFile {
-  version: 1;
-  devices: ApprovedDevice[];
-}
-
-function getStorePath(): string {
-  return join(getGatewaySecurityDir(), "approved-devices.json");
-}
-
-/** Hash a raw deviceId for storage. */
-export function hashDeviceId(deviceId: string): string {
-  return createHash("sha256").update(deviceId).digest("hex");
-}
-
-let cachedDevices: Map<string, ApprovedDevice> | null = null;
-
-function loadFromDisk(): Map<string, ApprovedDevice> {
-  const path = getStorePath();
-  if (!existsSync(path)) {
-    return new Map();
-  }
-  try {
-    const raw = readFileSync(path, "utf-8");
-    const data = JSON.parse(raw) as ApprovedDevicesFile;
-    if (data.version !== 1 || !Array.isArray(data.devices)) {
-      log.warn("Invalid approved-devices.json format, starting fresh");
-      return new Map();
-    }
-    const map = new Map<string, ApprovedDevice>();
-    for (const device of data.devices) {
-      map.set(device.hashedDeviceId, device);
-    }
-    return map;
-  } catch (err) {
-    log.error({ err }, "Failed to load approved-devices.json");
-    return new Map();
-  }
-}
-
-function saveToDisk(devices: Map<string, ApprovedDevice>): void {
-  const path = getStorePath();
-  const dir = dirname(path);
-  if (!existsSync(dir)) {
-    mkdirSync(dir, { recursive: true });
-  }
-  const data: ApprovedDevicesFile = {
-    version: 1,
-    devices: Array.from(devices.values()),
-  };
-  const tmpPath = path + ".tmp." + process.pid;
-  writeFileSync(tmpPath, JSON.stringify(data, null, 2), { mode: 0o600 });
-  renameSync(tmpPath, path);
-  chmodSync(path, 0o600);
-}
-
-function getDevices(): Map<string, ApprovedDevice> {
-  if (cachedDevices == null) {
-    cachedDevices = loadFromDisk();
-  }
-  return cachedDevices;
-}
-
-/** Check if a hashed device ID is in the allowlist. */
-export function isDeviceApproved(hashedDeviceId: string): boolean {
-  return getDevices().has(hashedDeviceId);
-}
-
-/** Update lastPairedAt and deviceName for an existing device (auto-approve refresh). */
-export function refreshDevice(
-  hashedDeviceId: string,
-  deviceName: string,
-): void {
-  const devices = getDevices();
-  const existing = devices.get(hashedDeviceId);
-  if (existing) {
-    existing.deviceName = deviceName;
-    existing.lastPairedAt = Date.now();
-    saveToDisk(devices);
-    log.info({ hashedDeviceId }, "Device metadata refreshed");
-  }
-}