@vellumai/cli 0.11.2 → 0.11.3-staging.2

package/node_modules/@vellumai/local-mode/src/gateway-proxy.ts

@@ -1,7 +1,13 @@
 import fs from "node:fs";
 
+import type { TokenResult } from "./guardian-token";
+import { isUsableRuntimeUrl, resolveCloud } from "./lockfile-contract";
+
 const GATEWAY_PATTERN = /^(?:\/assistant)?\/__gateway\/(\d+)(\/.*)?$/;
 
+const PAIRED_GATEWAY_PATTERN =
+  /^(?:\/assistant)?\/__gateway-paired\/([^/?#]+)(\/.*)?$/;
+
 export interface GatewayTarget {
   port: number;
   path: string;
@@ -64,6 +70,191 @@ export function resolveGatewayProxyTarget(
   return { kind: "forward", target: parsed.target };
 }
 
+export interface PairedGatewayTarget {
+  assistantId: string;
+  /** Pathname tail forwarded onto the runtimeUrl, without the query. */
+  path: string;
+  /** Query string including the leading `?`, or empty. */
+  search: string;
+}
+
+export type PairedGatewayParseResult =
+  | { match: true; valid: true; target: PairedGatewayTarget }
+  | { match: true; valid: false }
+  | { match: false };
+
+/**
+ * A tail containing a `.` or `..` path segment (raw or percent-encoded) could
+ * escape the runtimeUrl's recorded path prefix on hosts that forward the tail
+ * un-normalized, so it is an invalid parse. A segment whose percent-encoding
+ * doesn't decode is rejected for the same reason: it can't be verified.
+ */
+function hasDotSegment(path: string): boolean {
+  for (const segment of path.split("/")) {
+    let decoded: string;
+    try {
+      decoded = decodeURIComponent(segment);
+    } catch {
+      return true;
+    }
+    if (decoded === "." || decoded === "..") {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Parse a paired-gateway URL given as `pathname + search` (a `#fragment`
+ * suffix is tolerated and dropped), so every host hands over the same shape
+ * and the decision is host-independent.
+ */
+export function parsePairedGatewayUrl(url: string): PairedGatewayParseResult {
+  const delimiter = url.search(/[?#]/);
+  const pathname = delimiter === -1 ? url : url.slice(0, delimiter);
+  const suffix = delimiter === -1 ? "" : url.slice(delimiter);
+  const search = suffix.startsWith("?") ? (suffix.split("#")[0] ?? "") : "";
+
+  const match = pathname.match(PAIRED_GATEWAY_PATTERN);
+  if (!match) {
+    return { match: false };
+  }
+
+  let assistantId: string;
+  try {
+    assistantId = decodeURIComponent(match[1]!);
+  } catch {
+    // Malformed percent-encoding is an invalid parse, not a crash.
+    return { match: true, valid: false };
+  }
+
+  const path = match[2] || "/";
+  if (hasDotSegment(path)) {
+    return { match: true, valid: false };
+  }
+
+  return {
+    match: true,
+    valid: true,
+    target: { assistantId, path, search },
+  };
+}
+
+/**
+ * Verdict for a paired-gateway proxy URL (`/__gateway-paired/{assistantId}/*`),
+ * combining the URL parse with the lockfile pairing-allowlist check into one
+ * decision a host can act on without re-deriving the rules.
+ *
+ *   - `pass`: not a paired-gateway URL; the host serves it normally.
+ *   - `reject`: a paired-gateway URL whose id is malformed, whose tail is a
+ *     traversal attempt, or whose id is not paired in the lockfile (the
+ *     security boundary: the proxy only reaches gateways of entries the user
+ *     actually imported, never arbitrary URLs). Carries the status and
+ *     message the host answers with, so hosts don't restate them.
+ *   - `forward`: forward to `url` (the entry's recorded runtimeUrl with the
+ *     request path and query appended). Carries the paired assistant id so
+ *     the trusted host can resolve its guardian bearer.
+ */
+export type PairedGatewayProxyDecision =
+  | { kind: "pass" }
+  | { kind: "reject"; status: number; message: string }
+  | {
+      kind: "forward";
+      url: string;
+      runtimeUrl: string;
+      assistantId: string;
+    };
+
+const PAIRED_GATEWAY_REJECTION: PairedGatewayProxyDecision = {
+  kind: "reject",
+  status: 403,
+  message: "Assistant is not paired in lockfile",
+};
+
+/**
+ * Resolve a request URL, given as `pathname + search`, to a paired-gateway
+ * proxy verdict. Identical across every host that proxies the data plane,
+ * mirroring {@link resolveGatewayProxyTarget}.
+ *
+ * `getTargets` is a thunk (typically `() => readPairedGatewayTargets(...)`) so
+ * the lockfile is read only once a paired-gateway URL is matched.
+ */
+export function resolvePairedGatewayProxyTarget(
+  url: string,
+  getTargets: () => Map<string, string>,
+): PairedGatewayProxyDecision {
+  const parsed = parsePairedGatewayUrl(url);
+  if (!parsed.match) {
+    return { kind: "pass" };
+  }
+  if (!parsed.valid) {
+    return PAIRED_GATEWAY_REJECTION;
+  }
+  const runtimeUrl = getTargets().get(parsed.target.assistantId);
+  if (!runtimeUrl) {
+    return PAIRED_GATEWAY_REJECTION;
+  }
+  // Preserve the runtimeUrl's own path prefix (minus trailing slashes), then
+  // append the request path and query.
+  return {
+    kind: "forward",
+    url: `${runtimeUrl.replace(/\/+$/, "")}${parsed.target.path}${parsed.target.search}`,
+    runtimeUrl,
+    assistantId: parsed.target.assistantId,
+  };
+}
+
+/**
+ * Strip renderer-controlled and browser-ambient headers from a paired forward
+ * before the remote hop. The trusted host installs its own guardian bearer
+ * after this function returns, so a renderer-provided `Authorization` header
+ * can never select or override the credential sent upstream.
+ */
+export function sanitizePairedForwardHeaders(headers: Headers): void {
+  const secFetchNames: string[] = [];
+  headers.forEach((_value, name) => {
+    if (name.toLowerCase().startsWith("sec-fetch-")) {
+      secFetchNames.push(name);
+    }
+  });
+  for (const name of secFetchNames) {
+    headers.delete(name);
+  }
+  headers.delete("origin");
+  headers.delete("referer");
+  headers.delete("cookie");
+  headers.delete("authorization");
+  // Paired runtimeUrls are commonly ngrok tunnels; free-tier ngrok answers
+  // browser User-Agents with an interstitial page (ERR_NGROK_6024) unless
+  // this header is present. Harmless for every other target.
+  headers.set("ngrok-skip-browser-warning", "true");
+}
+
+export type PairedGuardianTokenProvider = (
+  assistantId: string,
+  runtimeUrl: string,
+) => Promise<TokenResult>;
+
+export type PairedForwardAuthorizationResult =
+  | { ok: true }
+  | { ok: false; status: number; error: string };
+
+/** Replace renderer authorization with the paired credential owned by the host. */
+export async function authorizePairedForwardHeaders(
+  assistantId: string,
+  runtimeUrl: string,
+  headers: Headers,
+  getGuardianToken: PairedGuardianTokenProvider,
+): Promise<PairedForwardAuthorizationResult> {
+  sanitizePairedForwardHeaders(headers);
+  const result = await getGuardianToken(assistantId, runtimeUrl);
+  if (!result.ok) {
+    return result;
+  }
+  headers.set("authorization", `Bearer ${result.accessToken}`);
+  return { ok: true };
+}
+
 function addPortFromUrl(url: unknown, ports: Set<number>): void {
   if (typeof url !== "string") return;
   try {
@@ -78,37 +269,134 @@ function addPortFromUrl(url: unknown, ports: Set<number>): void {
   }
 }
 
+type LockfileEntriesRead =
+  | { kind: "ok"; assistants: unknown[] }
+  | { kind: "missing" }
+  | { kind: "unreadable" };
+
+/**
+ * Read one lockfile candidate's raw `assistants` array. `missing` is an
+ * absent file; `unreadable` is any other read failure or malformed JSON. The
+ * one read-loop body both gateway-proxy readers share; how a caller walks the
+ * candidate list on `missing`/`unreadable` is its own posture.
+ */
+function readLockfileAssistantEntries(candidate: string): LockfileEntriesRead {
+  let raw: string;
+  try {
+    raw = fs.readFileSync(candidate, "utf-8");
+  } catch (err: unknown) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+      return { kind: "missing" };
+    }
+    return { kind: "unreadable" };
+  }
+  try {
+    const data = JSON.parse(raw) as { assistants?: unknown };
+    return {
+      kind: "ok",
+      assistants: Array.isArray(data.assistants) ? data.assistants : [],
+    };
+  } catch {
+    return { kind: "unreadable" };
+  }
+}
+
 export function readAllowedGatewayPorts(lockfilePaths: string[]): Set<number> {
   const ports = new Set<number>();
   for (const candidate of lockfilePaths) {
-    try {
-      const raw = fs.readFileSync(candidate, "utf-8");
-      const data = JSON.parse(raw) as {
-        assistants?: Array<{
-          gatewayUrl?: unknown;
-          localUrl?: unknown;
-          runtimeUrl?: unknown;
-          resources?: { gatewayPort?: unknown };
-        }>;
+    const read = readLockfileAssistantEntries(candidate);
+    if (read.kind === "missing") {
+      continue;
+    }
+    if (read.kind === "unreadable") {
+      return new Set<number>();
+    }
+    for (const entry of read.assistants) {
+      if (!entry || typeof entry !== "object") {
+        continue;
+      }
+      const assistant = entry as {
+        cloud?: unknown;
+        project?: unknown;
+        sshUser?: unknown;
+        gatewayUrl?: unknown;
+        localUrl?: unknown;
+        runtimeUrl?: unknown;
+        resources?: { gatewayPort?: unknown };
       };
-      const assistants = Array.isArray(data.assistants) ? data.assistants : [];
-      for (const assistant of assistants) {
-        if (!assistant) continue;
-        addPortFromUrl(assistant.gatewayUrl, ports);
-        addPortFromUrl(assistant.localUrl, ports);
-        // Docker entries record their published gateway as a loopback
-        // `runtimeUrl` with no `resources` block; the loopback-hostname filter
-        // in addPortFromUrl keeps remote runtimeUrls out of the allowlist.
-        addPortFromUrl(assistant.runtimeUrl, ports);
-        const gp = assistant.resources?.gatewayPort;
-        if (typeof gp === "number" && Number.isInteger(gp) && gp >= 1024 && gp <= 65535) {
-          ports.add(gp);
-        }
+      // A paired entry's gateway is remote by contract and reached through the
+      // paired proxy; even a (rejected-on-import, but possibly pre-existing)
+      // loopback runtimeUrl must never open the generic loopback proxy.
+      if (resolveCloud(assistant) === "paired") {
+        continue;
       }
-      if (ports.size > 0) return ports;
-    } catch (err: unknown) {
-      if ((err as NodeJS.ErrnoException).code !== "ENOENT") return new Set<number>();
+      addPortFromUrl(assistant.gatewayUrl, ports);
+      addPortFromUrl(assistant.localUrl, ports);
+      // Docker entries record their published gateway as a loopback
+      // `runtimeUrl` with no `resources` block; the loopback-hostname filter
+      // in addPortFromUrl keeps remote runtimeUrls out of the allowlist.
+      addPortFromUrl(assistant.runtimeUrl, ports);
+      const gp = assistant.resources?.gatewayPort;
+      if (typeof gp === "number" && Number.isInteger(gp) && gp >= 1024 && gp <= 65535) {
+        ports.add(gp);
+      }
+    }
+    if (ports.size > 0) {
+      return ports;
     }
   }
   return ports;
 }
+
+/**
+ * Compute the paired-gateway allowlist from a lockfile's assistant entries:
+ * assistantId to the recorded remote `runtimeUrl`, for entries whose resolved
+ * cloud is "paired" and whose runtimeUrl is usable
+ * ({@link isUsableRuntimeUrl}). Tolerant of malformed entries. Pure, so a host
+ * holding an in-memory lockfile snapshot (e.g. the Electron lockfile watcher)
+ * derives the allowlist without touching disk on the request path.
+ */
+export function pairedGatewayTargetsFromLockfile(lockfile: {
+  assistants: readonly unknown[];
+}): Map<string, string> {
+  const targets = new Map<string, string>();
+  for (const entry of lockfile.assistants) {
+    if (!entry || typeof entry !== "object") {
+      continue;
+    }
+    const assistant = entry as Record<string, unknown>;
+    if (resolveCloud(assistant) !== "paired") {
+      continue;
+    }
+    const { assistantId, runtimeUrl } = assistant;
+    if (typeof assistantId !== "string" || assistantId === "") {
+      continue;
+    }
+    if (typeof runtimeUrl !== "string" || !isUsableRuntimeUrl(runtimeUrl)) {
+      continue;
+    }
+    targets.set(assistantId, runtimeUrl);
+  }
+  return targets;
+}
+
+/**
+ * Read the paired-gateway allowlist from the lockfile on disk
+ * ({@link pairedGatewayTargetsFromLockfile} over the first readable
+ * candidate). Path selection matches the unpair write path (`readRawLockfile`
+ * in lockfile.ts): the first readable, parseable lockfile is authoritative
+ * even when it yields no targets, so a pairing removed by an unpair write can
+ * never survive in a stale fallback file's allowlist.
+ */
+export function readPairedGatewayTargets(
+  lockfilePaths: string[],
+): Map<string, string> {
+  for (const candidate of lockfilePaths) {
+    const read = readLockfileAssistantEntries(candidate);
+    if (read.kind !== "ok") {
+      continue;
+    }
+    return pairedGatewayTargetsFromLockfile({ assistants: read.assistants });
+  }
+  return new Map<string, string>();
+}

package/node_modules/@vellumai/local-mode/src/guardian-token.ts

@@ -1,16 +1,104 @@
 import { spawn } from "node:child_process";
 import fs from "node:fs";
+import path from "node:path";
 
-import { guardianTokenPath } from "./config";
+import { guardianTokenPath, resolveConfigDirPaths } from "./config";
 import type { CliInvocation } from "./util";
 
 const GUARDIAN_TOKEN_REFRESH_TIMEOUT_MS = 15_000;
+const guardianTokenRefreshes = new Map<string, Promise<TokenResult>>();
 
-interface GuardianTokenData {
+export const PAIRED_GUARDIAN_TOKEN_HOST_ONLY_ERROR =
+  "Paired assistant credentials are available only through the paired gateway proxy";
+export const PAIRED_GUARDIAN_TARGET_MISMATCH_ERROR =
+  "Paired assistant target does not match the stored pairing";
+
+/** The persisted shape of an assistant's guardian token file. */
+export interface GuardianTokenData {
+  guardianPrincipalId: string;
   accessToken: string;
+  /** ISO date string or epoch-ms number as returned by the gateway. */
   accessTokenExpiresAt: string | number;
   refreshToken: string;
+  /** ISO date string or epoch-ms number as returned by the gateway. */
   refreshTokenExpiresAt: string | number;
+  refreshAfter: string;
+  isNew: boolean;
+  deviceId: string;
+  leasedAt: string;
+  /** Remote gateway bound to a credential imported through the pairing flow. */
+  pairedGatewayUrl?: string;
+}
+
+/**
+ * Persist an assistant's guardian token where every host-seam reader resolves
+ * it (`guardianTokenPath`). The per-assistant directory is created 0700 and the
+ * file written 0600; chmod after the write covers a pre-existing file whose
+ * mode drifted.
+ */
+export function saveGuardianToken(
+  configDir: string,
+  assistantId: string,
+  data: GuardianTokenData,
+): void {
+  const tokenPath = guardianTokenPath(configDir, assistantId);
+  fs.mkdirSync(path.dirname(tokenPath), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(tokenPath, JSON.stringify(data, null, 2) + "\n", {
+    mode: 0o600,
+  });
+  fs.chmodSync(tokenPath, 0o600);
+}
+
+/**
+ * The guardian refresh token is long-lived and replayable, so it is only
+ * transmitted 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 {
+  // Strip URL brackets so IPv6 forms compare on the bare address.
+  const h = hostname.toLowerCase().replace(/^\[|\]$/g, "");
+  return (
+    h === "localhost" ||
+    h === "::1" ||
+    h === "0:0:0:0:0:0:0:1" ||
+    /^127(?:\.\d{1,3}){3}$/.test(h) ||
+    // Wildcard hosts reach a local listener when dialed (0.0.0.0 / ::), so
+    // they count as local for both the refresh-channel and pairing guards.
+    h === "0.0.0.0" ||
+    h === "0" ||
+    h === "::" ||
+    h === "0:0:0:0:0:0:0:0" ||
+    // IPv4-mapped loopback and wildcard, in dotted and hex encodings.
+    /^(?:0:0:0:0:0|:):ffff:127(?:\.\d{1,3}){3}$/.test(h) ||
+    /^(?:0:0:0:0:0|:):ffff:7f[0-9a-f]{2}:[0-9a-f]{1,4}$/.test(h) ||
+    /^(?:0:0:0:0:0|:):ffff:0\.0\.0\.0$/.test(h) ||
+    /^(?:0:0:0:0:0|:):ffff:0:0$/.test(h)
+  );
+}
+
+export function isConfidentialRefreshUrl(gatewayUrl: string): boolean {
+  try {
+    const url = new URL(gatewayUrl);
+    return url.protocol === "https:" || isLoopbackHostname(url.hostname);
+  } catch {
+    return false;
+  }
+}
+
+/** Whether a URL's host is loopback; false for unparseable URLs. */
+export function isLoopbackUrl(url: string): boolean {
+  try {
+    return isLoopbackHostname(new URL(url).hostname);
+  } catch {
+    return false;
+  }
 }
 
 function isAccessTokenExpired(data: GuardianTokenData): boolean {
@@ -29,31 +117,109 @@ export type TokenResult =
   | { ok: true; accessToken: string }
   | { ok: false; status: number; error: string };
 
+export interface GuardianTokenOptions {
+  /**
+   * True when the entry was imported from another machine via `vellum pair`.
+   * A paired entry has no local daemon, so expired-refresh guidance points at
+   * re-pairing instead of `vellum hatch`/`vellum wake`.
+   */
+  paired?: boolean;
+  /** Gateway URL resolved for the paired proxy request. */
+  pairedGatewayUrl?: string;
+}
+
 export function getGuardianAccessToken(
   assistantId: string,
   configDir: string,
   invocation: CliInvocation,
   isLoopback: boolean,
   env?: Record<string, string>,
+  options?: GuardianTokenOptions,
 ): Promise<TokenResult> {
   if (!isLoopback) {
     return Promise.resolve({ ok: false, status: 403, error: "Forbidden" });
   }
 
-  const tokenPath = guardianTokenPath(configDir, assistantId);
-
-  let raw: string;
+  let tokenPaths: string[];
   try {
-    raw = fs.readFileSync(tokenPath, "utf-8");
+    const configDirs = [
+      configDir,
+      ...resolveConfigDirPaths({ ...process.env, ...env }),
+    ];
+    tokenPaths = [...new Set(configDirs)].map((dir) =>
+      guardianTokenPath(dir, assistantId),
+    );
   } catch {
-    return Promise.resolve({ ok: false, status: 404, error: "Guardian token not found" });
+    return Promise.resolve({
+      ok: false,
+      status: 400,
+      error: "Invalid assistant ID",
+    });
+  }
+
+  let raw: string | undefined;
+  let resolvedTokenPath: string | undefined;
+  for (const tokenPath of tokenPaths) {
+    try {
+      raw = fs.readFileSync(tokenPath, "utf-8");
+      resolvedTokenPath = tokenPath;
+      break;
+    } catch {
+      // Try the next compatible location.
+    }
+  }
+  if (raw === undefined || resolvedTokenPath === undefined) {
+    return Promise.resolve({
+      ok: false,
+      status: 404,
+      error: "Guardian token not found",
+    });
   }
 
   let data: GuardianTokenData;
   try {
     data = JSON.parse(raw) as GuardianTokenData;
   } catch {
-    return Promise.resolve({ ok: false, status: 500, error: "Malformed guardian token file" });
+    return Promise.resolve({
+      ok: false,
+      status: 500,
+      error: "Malformed guardian token file",
+    });
+  }
+
+  if (data.pairedGatewayUrl) {
+    if (!options?.paired) {
+      return Promise.resolve({
+        ok: false,
+        status: 403,
+        error: PAIRED_GUARDIAN_TOKEN_HOST_ONLY_ERROR,
+      });
+    }
+    if (options.pairedGatewayUrl !== data.pairedGatewayUrl) {
+      return Promise.resolve({
+        ok: false,
+        status: 403,
+        error: PAIRED_GUARDIAN_TARGET_MISMATCH_ERROR,
+      });
+    }
+  } else if (options?.paired) {
+    if (!options.pairedGatewayUrl) {
+      return Promise.resolve({
+        ok: false,
+        status: 403,
+        error: PAIRED_GUARDIAN_TARGET_MISMATCH_ERROR,
+      });
+    }
+    data = { ...data, pairedGatewayUrl: options.pairedGatewayUrl };
+    try {
+      saveGuardianToken(configDir, assistantId, data);
+    } catch {
+      return Promise.resolve({
+        ok: false,
+        status: 500,
+        error: "Failed to bind paired assistant credential",
+      });
+    }
   }
 
   if (!isAccessTokenExpired(data)) {
@@ -64,11 +230,42 @@ export function getGuardianAccessToken(
     return Promise.resolve({
       ok: false,
       status: 401,
-      error: "Guardian token expired — re-run `vellum hatch` or `vellum wake`",
+      error: options?.paired
+        ? "Guardian token expired. Run `vellum pair` on the assistant's machine, then re-import it from the app's connect flow or with `vellum connect import`."
+        : "Guardian token expired. Re-run `vellum hatch` or `vellum wake`.",
     });
   }
 
-  return refreshToken(assistantId, invocation, env);
+  const existingRefresh = guardianTokenRefreshes.get(resolvedTokenPath);
+  if (existingRefresh) {
+    return existingRefresh;
+  }
+  const refresh = refreshToken(assistantId, invocation, env).finally(() => {
+    if (guardianTokenRefreshes.get(resolvedTokenPath) === refresh) {
+      guardianTokenRefreshes.delete(resolvedTokenPath);
+    }
+  });
+  guardianTokenRefreshes.set(resolvedTokenPath, refresh);
+  return refresh;
+}
+
+/** Resolve a paired bearer only when the proxy target matches its binding. */
+export function getPairedGuardianAccessToken(
+  assistantId: string,
+  pairedGatewayUrl: string,
+  configDir: string,
+  invocation: CliInvocation,
+  isLoopback: boolean,
+  env?: Record<string, string>,
+): Promise<TokenResult> {
+  return getGuardianAccessToken(
+    assistantId,
+    configDir,
+    invocation,
+    isLoopback,
+    env,
+    { paired: true, pairedGatewayUrl },
+  );
 }
 
 function refreshToken(
@@ -95,7 +292,11 @@ function refreshToken(
 
     const timeout = setTimeout(() => {
       child.kill("SIGTERM");
-      finish({ ok: false, status: 500, error: "Guardian token refresh timed out" });
+      finish({
+        ok: false,
+        status: 500,
+        error: "Guardian token refresh timed out",
+      });
     }, GUARDIAN_TOKEN_REFRESH_TIMEOUT_MS);
 
     child.stdout.on("data", (chunk: Buffer) => {
@@ -111,12 +312,20 @@ function refreshToken(
           finish({ ok: false, status: 500, error: "CLI returned empty token" });
         }
       } else {
-        finish({ ok: false, status: 401, error: "Failed to refresh guardian token" });
+        finish({
+          ok: false,
+          status: 401,
+          error: "Failed to refresh guardian token",
+        });
       }
     });
 
     child.on("error", (err) => {
-      finish({ ok: false, status: 500, error: `Failed to spawn CLI: ${err.message}` });
+      finish({
+        ok: false,
+        status: 500,
+        error: `Failed to spawn CLI: ${err.message}`,
+      });
     });
   });
 }