@vellumai/cli 0.8.8 → 0.8.9-dev.202606091926.ebb2d62

package/src/lib/flag-args.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, test, spyOn } from "bun:test";
+
+import { parseFeatureFlagArgs } from "./flag-args";
+
+describe("parseFeatureFlagArgs", () => {
+  test("single flag produces env var and empty remaining", () => {
+    const result = parseFeatureFlagArgs(["--flag", "voice-mode=true"]);
+    expect(result).toEqual({
+      envVars: { VELLUM_FLAG_VOICE_MODE: "true" },
+      remaining: [],
+    });
+  });
+
+  test("multiple flags produce multiple env vars", () => {
+    const result = parseFeatureFlagArgs([
+      "--flag",
+      "a=1",
+      "--flag",
+      "b=0",
+    ]);
+    expect(result).toEqual({
+      envVars: { VELLUM_FLAG_A: "1", VELLUM_FLAG_B: "0" },
+      remaining: [],
+    });
+  });
+
+  test("flags mixed with other args preserves remaining", () => {
+    const result = parseFeatureFlagArgs([
+      "--watch",
+      "--flag",
+      "x=y",
+      "--name",
+      "foo",
+    ]);
+    expect(result).toEqual({
+      envVars: { VELLUM_FLAG_X: "y" },
+      remaining: ["--watch", "--name", "foo"],
+    });
+  });
+
+  test("exits with error when --flag has no following argument", () => {
+    const exitSpy = spyOn(process, "exit").mockImplementation(() => {
+      throw new Error("process.exit");
+    });
+    const errorSpy = spyOn(console, "error").mockImplementation(() => {});
+
+    expect(() => parseFeatureFlagArgs(["--flag"])).toThrow("process.exit");
+    expect(errorSpy).toHaveBeenCalledWith(
+      "Error: --flag requires a key=value argument",
+    );
+
+    exitSpy.mockRestore();
+    errorSpy.mockRestore();
+  });
+
+  test("exits with error when value has no equals sign", () => {
+    const exitSpy = spyOn(process, "exit").mockImplementation(() => {
+      throw new Error("process.exit");
+    });
+    const errorSpy = spyOn(console, "error").mockImplementation(() => {});
+
+    expect(() => parseFeatureFlagArgs(["--flag", "noequals"])).toThrow(
+      "process.exit",
+    );
+    expect(errorSpy).toHaveBeenCalledWith(
+      'Error: --flag value must be in key=value format, got "noequals"',
+    );
+
+    exitSpy.mockRestore();
+    errorSpy.mockRestore();
+  });
+
+  test("exits with error when key is not kebab-case", () => {
+    const exitSpy = spyOn(process, "exit").mockImplementation(() => {
+      throw new Error("process.exit");
+    });
+    const errorSpy = spyOn(console, "error").mockImplementation(() => {});
+
+    expect(() => parseFeatureFlagArgs(["--flag", "UPPER=true"])).toThrow(
+      "process.exit",
+    );
+    expect(errorSpy).toHaveBeenCalledWith(
+      'Error: invalid flag key "UPPER". Keys must be kebab-case (e.g. "voice-mode")',
+    );
+
+    exitSpy.mockRestore();
+    errorSpy.mockRestore();
+  });
+});

package/src/lib/flag-args.ts

@@ -0,0 +1,74 @@
+/** Only allow simple kebab-case keys (e.g. "voice-mode", "ces-tools"). */
+const ALLOWED_KEY_RE = /^[a-z0-9][a-z0-9-]*$/;
+
+/**
+ * Extract repeatable `--flag key=value` pairs from a CLI arg list.
+ *
+ * Each `--flag` consumes the next argument as `key=value`. Keys are validated
+ * against a kebab-case pattern, then converted to env var names of the form
+ * `VELLUM_FLAG_<UPPER_SNAKE>`. All `--flag` pairs are stripped from the
+ * returned `remaining` array so downstream parsers never see them.
+ */
+export function parseFeatureFlagArgs(args: string[]): {
+  envVars: Record<string, string>;
+  remaining: string[];
+} {
+  const envVars: Record<string, string> = {};
+  const remaining: string[] = [];
+
+  let i = 0;
+  while (i < args.length) {
+    if (args[i] === "--flag") {
+      if (i + 1 >= args.length) {
+        console.error("Error: --flag requires a key=value argument");
+        process.exit(1);
+      }
+
+      const pair = args[i + 1]!;
+      const eqIdx = pair.indexOf("=");
+      if (eqIdx === -1) {
+        console.error(
+          `Error: --flag value must be in key=value format, got "${pair}"`,
+        );
+        process.exit(1);
+      }
+
+      const key = pair.slice(0, eqIdx);
+      const value = pair.slice(eqIdx + 1);
+
+      if (!ALLOWED_KEY_RE.test(key)) {
+        console.error(
+          `Error: invalid flag key "${key}". Keys must be kebab-case (e.g. "voice-mode")`,
+        );
+        process.exit(1);
+      }
+
+      const envName = `VELLUM_FLAG_${key.toUpperCase().replace(/-/g, "_")}`;
+      envVars[envName] = value;
+      i += 2;
+    } else {
+      remaining.push(args[i]!);
+      i += 1;
+    }
+  }
+
+  return { envVars, remaining };
+}
+
+const ENV_FLAG_PREFIX = "VELLUM_FLAG_";
+
+/**
+ * Scan `process.env` for ambient `VELLUM_FLAG_*` entries.
+ * Returns them as-is (same `Record<string, string>` shape as
+ * `parseFeatureFlagArgs().envVars`) so callers can merge both
+ * sources with `--flag` args winning over ambient env vars.
+ */
+export function readAmbientFlagEnvVars(): Record<string, string> {
+  const vars: Record<string, string> = {};
+  for (const [key, value] of Object.entries(process.env)) {
+    if (key.startsWith(ENV_FLAG_PREFIX) && value !== undefined) {
+      vars[key] = value;
+    }
+  }
+  return vars;
+}

package/src/lib/guardian-token.ts

@@ -254,10 +254,64 @@ function releaseRefreshLock(lockPath: string): void {
  * process already rotated it while we waited, we return that fresh token
  * instead of replaying our now-stale refresh token.
  */
+/**
+ * The guardian refresh token is long-lived and replayable, so we only transmit
+ * it over a confidential channel: HTTPS, or a loopback host (local dev, or a
+ * same-host reverse proxy / tunnel agent). Refreshing against a non-loopback
+ * plaintext `http://` URL is refused — an on-path attacker could otherwise
+ * capture the refresh token and rotate it into fresh credentials.
+ *
+ * A user-chosen malicious `https://` destination is intentionally out of scope:
+ * HTTPS protects the channel, and the access token already goes wherever the
+ * configured URL points. This guard targets the plaintext-interception vector.
+ */
+function isLoopbackHostname(hostname: string): boolean {
+  const h = hostname.toLowerCase();
+  return (
+    h === "localhost" ||
+    h === "::1" ||
+    h === "[::1]" ||
+    h === "0:0:0:0:0:0:0:1" ||
+    /^127(?:\.\d{1,3}){3}$/.test(h)
+  );
+}
+
+function isConfidentialRefreshUrl(gatewayUrl: string): boolean {
+  try {
+    const url = new URL(gatewayUrl);
+    return url.protocol === "https:" || isLoopbackHostname(url.hostname);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * True when a stored guardian token has reached its renewal point — now is
+ * at/after `refreshAfter` (preferred) or `accessTokenExpiresAt`. Used to gate
+ * refresh so a forged/synthetic 401 on a still-valid token can't coax out the
+ * long-lived refresh credential. Unparseable timestamps → not due.
+ */
+export function guardianTokenDueForRenewal(token: GuardianTokenData): boolean {
+  const raw = token.refreshAfter || token.accessTokenExpiresAt;
+  const at = new Date(raw).getTime();
+  if (!Number.isFinite(at)) return false;
+  return at <= Date.now();
+}
+
 export async function refreshGuardianToken(
   gatewayUrl: string,
   assistantId: string,
 ): Promise<GuardianTokenData | null> {
+  // Never send the long-lived refresh token over a non-loopback plaintext URL.
+  if (!isConfidentialRefreshUrl(gatewayUrl)) {
+    console.warn(
+      `Refusing to refresh the guardian token over an insecure URL (${gatewayUrl}). ` +
+        "The refresh token is only sent over https or a loopback address — " +
+        "use an https URL (e.g. a tunnel) or connect over loopback.",
+    );
+    return null;
+  }
+
   const before = loadGuardianToken(assistantId);
   if (!before) return null;
 

package/src/lib/hatch-local.ts

@@ -164,6 +164,7 @@ export async function hatchLocal(
   watch: boolean = false,
   keepAlive: boolean = false,
   configValues: Record<string, string> = {},
+  flagEnvVars: Record<string, string> = {},
   options: HatchLocalOptions = {},
 ): Promise<HatchLocalResult> {
   const reporter = options.reporter ?? consoleLifecycleReporter;
@@ -234,6 +235,7 @@ export async function hatchLocal(
     runtimeUrl = await startGateway(watch, resources, {
       signingKey,
       bootstrapSecret,
+      envOverrides: flagEnvVars,
     });
   } catch (error) {
     // Gateway failed — stop the daemon we just started so we don't leave

package/src/lib/local.ts

@@ -1057,7 +1057,11 @@ export async function startLocalDaemon(
 export async function startGateway(
   watch: boolean = false,
   resources?: LocalInstanceResources,
-  options?: { signingKey?: string; bootstrapSecret?: string },
+  options?: {
+    signingKey?: string;
+    bootstrapSecret?: string;
+    envOverrides?: Record<string, string>;
+  },
 ): Promise<string> {
   const effectiveGatewayPort = resources?.gatewayPort ?? GATEWAY_PORT;
 
@@ -1083,6 +1087,7 @@ export async function startGateway(
 
   const gatewayEnv: Record<string, string> = {
     ...(process.env as Record<string, string>),
+    ...options?.envOverrides,
     RUNTIME_HTTP_PORT: String(effectiveDaemonPort),
     GATEWAY_PORT: String(effectiveGatewayPort),
     // Pass gateway operational settings via env vars so the CLI does not

package/src/lib/runtime-url.ts

@@ -1,3 +1,6 @@
+import { hostname } from "node:os";
+
+import { getLocalLanIPv4 } from "./local";
 import type { AssistantEntry } from "./assistant-config.js";
 
 /**
@@ -50,3 +53,90 @@ export function resolveRuntimeUrl(
   }
   return `${entry.runtimeUrl}/v1/${subpath}`;
 }
+
+/**
+ * If the hostname in `url` matches this machine's local DNS name, LAN IP, or
+ * raw hostname, replace it with 127.0.0.1 so the client avoids mDNS round-trips
+ * when talking to an assistant running on the same machine. Trailing slashes are
+ * stripped on a swap. Returns the input unchanged if it doesn't parse as a URL.
+ */
+function maybeSwapToLocalhost(url: string): string {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return url;
+  }
+
+  const urlHost = parsed.hostname.toLowerCase();
+
+  const localNames: string[] = [];
+
+  const host = hostname();
+  if (host) {
+    localNames.push(host.toLowerCase());
+    // Also consider the bare name without .local suffix
+    if (host.toLowerCase().endsWith(".local")) {
+      localNames.push(host.toLowerCase().slice(0, -".local".length));
+    }
+  }
+
+  const lanIp = getLocalLanIPv4();
+  if (lanIp) {
+    localNames.push(lanIp);
+  }
+
+  if (localNames.includes(urlHost)) {
+    parsed.hostname = "127.0.0.1";
+    return parsed.toString().replace(/\/+$/, "");
+  }
+
+  return url;
+}
+
+/**
+ * Canonical form of a runtime/base URL used throughout the CLI: trailing
+ * slashes stripped, then localhost-swapped. This is exactly the transform
+ * `vellum client` applies to the runtime URL it hands the TUI, so comparing two
+ * URLs after passing both through this function is a like-for-like comparison.
+ */
+export function normalizeRuntimeUrl(url: string): string {
+  return maybeSwapToLocalhost(url.replace(/\/+$/, ""));
+}
+
+/**
+ * SECURITY: decide whether a guardian-token refresh may be sent to
+ * `candidateUrl`, and to which URL it should actually go.
+ *
+ * `vellum client` lets `--url`/`-u` override the runtime URL while still reusing
+ * the selected entry's stored guardian token, so a victim pointed at an
+ * attacker-controlled (or poisoned/redirected) URL must NOT cause us to POST the
+ * long-lived refreshToken + deviceId there. Refresh is permitted only when
+ * `candidateUrl` normalizes to one of the entry's persisted URLs (`localUrl`,
+ * which the CLI prefers when present, or `runtimeUrl`).
+ *
+ * Returns the persisted URL that the candidate matched — never the
+ * caller-supplied `candidateUrl` verbatim — so credentials only ever reach a
+ * trusted origin even if a caller forgets to use this return value. The matched
+ * URL is preferred over always returning `runtimeUrl` so the refresh stays on
+ * the same interface the session is using: e.g. a local entry may persist both a
+ * loopback `localUrl` (which `vellum client` defaults to) and an externally
+ * discovered `runtimeUrl`, and refreshing the loopback session against the
+ * external address could be unreachable or needlessly cross the public
+ * interface. Returns `null` when the candidate is untrusted (caller must skip
+ * the refresh).
+ */
+export function trustedRefreshUrl(
+  entry: Pick<AssistantEntry, "runtimeUrl" | "localUrl">,
+  candidateUrl: string,
+): string | null {
+  const candidate = normalizeRuntimeUrl(candidateUrl);
+  // localUrl first: it's what the CLI prefers when present, so the candidate is
+  // most likely to match it, and we want to keep the refresh on that interface.
+  for (const persisted of [entry.localUrl, entry.runtimeUrl]) {
+    if (persisted && normalizeRuntimeUrl(persisted) === candidate) {
+      return persisted;
+    }
+  }
+  return null;
+}

package/src/lib/statefulset.ts

@@ -257,6 +257,7 @@ export interface BuildServiceRunArgsOpts extends DockerRunSecrets {
   instanceName: string;
   res: DockerResourceNames;
   extraAssistantEnv?: Record<string, string>;
+  extraGatewayEnv?: Record<string, string>;
   /** Avatar device path, if available. Injected by `docker.ts` after resolving. */
   avatarDevicePath?: string;
 }
@@ -285,6 +286,7 @@ export function buildServiceRunArgs(
     instanceName,
     res,
     extraAssistantEnv,
+    extraGatewayEnv,
     avatarDevicePath,
   } = opts;
 
@@ -346,6 +348,13 @@ export function buildServiceRunArgs(
         }
       }
 
+      // Gateway-only additions (e.g. feature flag env overrides)
+      if (svc === "gateway" && extraGatewayEnv) {
+        for (const [k, v] of Object.entries(extraGatewayEnv)) {
+          args.push("-e", `${k}=${v}`);
+        }
+      }
+
       // Assistant-only computed / optional additions
       if (svc === "assistant") {
         args.push(