@vellumai/cli 0.11.2 → 0.11.3-staging.2

package/node_modules/@vellumai/local-mode/src/index.ts

@@ -4,13 +4,15 @@
  * hatch/retire/wake lifecycle ops) over a loopback HTTP boundary. Consumed by the
  * CLI `client` server and the web app's dev-server middleware so the local
  * endpoint behaviour is defined exactly once instead of one host reaching into
- * another's source tree. Depends only on `@vellumai/environments`.
+ * another's source tree. `@vellumai/environments` is its only workspace
+ * dependency.
  */
 export {
   stripSensitiveFields,
   isLoopbackAddr,
   headerHostIsLoopback,
   originIsAllowed,
+  hasSameOriginCredentialProof,
   resolveDevCliInvocation,
 } from "./util";
 export type { CliInvocation } from "./util";
@@ -18,19 +20,28 @@ export {
   resolveLocalConfigFromEnv,
   resolveLockfilePaths,
   resolveConfigDir,
+  resolveConfigDirPaths,
+  resolveRuntimeDir,
+  resolveLogDir,
+  resolveAssistantsDir,
+  resolveInstanceDir,
   guardianTokenPath,
 } from "./config";
 export type { LocalEndpointConfig } from "./config";
+export type { LocalPathOptions } from "./paths";
 export {
   defaultEnvironmentFilePath,
+  defaultEnvironmentFilePaths,
   readDefaultEnvironment,
   resolveEnvironmentName,
 } from "./environment";
 export {
   getLockfileData,
   upsertLockfileAssistant,
+  upsertRendererLockfileAssistant,
   replacePlatformAssistants,
   isActiveAssistant,
+  isPairedLockfileEntry,
 } from "./lockfile";
 export type { LockfileResult, WriteResult } from "./lockfile";
 export { parseLockfile } from "./lockfile-contract";
@@ -44,6 +55,8 @@ export { runHatch } from "./hatch";
 export type { HatchResult } from "./hatch";
 export { runRetire } from "./retire";
 export type { RetireOptions, RetireResult } from "./retire";
+export { unpairAssistant } from "./unpair";
+export { decodePairBundle, pairAssistant, connectImport } from "./pair";
 export { runSleep } from "./sleep";
 export type { SleepResult } from "./sleep";
 export { runWake } from "./wake";
@@ -55,15 +68,34 @@ export type {
   LocalAssistantRuntimeState,
   LocalAssistantStatusResult,
 } from "./status";
-export { getGuardianAccessToken } from "./guardian-token";
-export type { TokenResult } from "./guardian-token";
 export {
+  getGuardianAccessToken,
+  getPairedGuardianAccessToken,
+  isConfidentialRefreshUrl,
+  PAIRED_GUARDIAN_TOKEN_HOST_ONLY_ERROR,
+  PAIRED_GUARDIAN_TARGET_MISMATCH_ERROR,
+  saveGuardianToken,
+} from "./guardian-token";
+export type {
+  TokenResult,
+  GuardianTokenData,
+  GuardianTokenOptions,
+} from "./guardian-token";
+export {
+  authorizePairedForwardHeaders,
   parseGatewayUrl,
   readAllowedGatewayPorts,
   resolveGatewayProxyTarget,
+  parsePairedGatewayUrl,
+  pairedGatewayTargetsFromLockfile,
+  readPairedGatewayTargets,
+  resolvePairedGatewayProxyTarget,
+  sanitizePairedForwardHeaders,
 } from "./gateway-proxy";
 export type {
   GatewayTarget,
   GatewayParseResult,
   GatewayProxyDecision,
+  PairedForwardAuthorizationResult,
+  PairedGuardianTokenProvider,
 } from "./gateway-proxy";

package/node_modules/@vellumai/local-mode/src/lockfile-contract.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, test } from "bun:test";
 
 import {
   KNOWN_CLOUDS,
+  pairedHostLabel,
   parseLockfile,
   resolveCloud,
   SENSITIVE_KEYS,
@@ -338,6 +339,23 @@ describe("resolveCloud", () => {
   });
 });
 
+describe("pairedHostLabel", () => {
+  test("names the remote host from a parseable runtimeUrl", () => {
+    expect(pairedHostLabel("https://tunnel.example.com")).toBe(
+      "Paired · tunnel.example.com",
+    );
+    expect(pairedHostLabel("https://remote-host.example:8443")).toBe(
+      "Paired · remote-host.example",
+    );
+  });
+
+  test("falls back to plain Paired for a missing or unparseable runtimeUrl", () => {
+    expect(pairedHostLabel(undefined)).toBe("Paired");
+    expect(pairedHostLabel("")).toBe("Paired");
+    expect(pairedHostLabel("not a url")).toBe("Paired");
+  });
+});
+
 describe("taxonomy", () => {
   test("KNOWN_CLOUDS covers the documented topologies", () => {
     expect(KNOWN_CLOUDS).toEqual([

package/node_modules/@vellumai/local-mode/src/lockfile-contract.ts

@@ -76,6 +76,78 @@ export function resolveCloud(raw: {
   return "local";
 }
 
+/**
+ * Whether an entry's `runtimeUrl` is one a serving host can forward to: an
+ * absolute http(s) URL. Shared by the renderer's paired-gateway URL derivation
+ * and the host-side paired allowlist reader so the two can't drift.
+ */
+export function isUsableRuntimeUrl(url: unknown): boolean {
+  if (typeof url !== "string" || url === "") {
+    return false;
+  }
+  try {
+    const parsed = new URL(url);
+    return parsed.protocol === "http:" || parsed.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * User-facing hosting label for a paired entry: "Paired · <hostname>" when
+ * `runtimeUrl` names the remote host, plain "Paired" otherwise. Shared by the
+ * macOS tray switcher and the web chooser so their renderings cannot drift.
+ */
+export function pairedHostLabel(runtimeUrl: string | undefined): string {
+  if (runtimeUrl) {
+    try {
+      return `Paired · ${new URL(runtimeUrl).hostname}`;
+    } catch {
+      // Unparseable runtimeUrl: plain "Paired".
+    }
+  }
+  return "Paired";
+}
+
+/**
+ * Clouds whose gateway listens on a loopback port of this machine: the
+ * on-machine daemon ("local") and local Docker instances ("docker").
+ */
+export const LOOPBACK_GATEWAY_CLOUDS: readonly Cloud[] = ["local", "docker"];
+
+export function isLoopbackGatewayCloud(cloud: Cloud): boolean {
+  return LOOPBACK_GATEWAY_CLOUDS.includes(cloud);
+}
+
+/**
+ * The loopback gateway port recorded for an assistant entry:
+ * `resources.gatewayPort` when present, else the port of a loopback
+ * `runtimeUrl` (how docker hatch records its published gateway). A
+ * non-loopback `runtimeUrl` yields nothing.
+ */
+export function getLoopbackGatewayPort(entry: {
+  resources?: { gatewayPort?: number };
+  runtimeUrl?: string;
+}): number | undefined {
+  const recorded = entry.resources?.gatewayPort;
+  if (recorded != null) {
+    return recorded;
+  }
+  if (!entry.runtimeUrl) {
+    return undefined;
+  }
+  try {
+    const url = new URL(entry.runtimeUrl);
+    if (url.hostname !== "localhost" && url.hostname !== "127.0.0.1") {
+      return undefined;
+    }
+    const port = Number(url.port);
+    return Number.isInteger(port) && port > 0 ? port : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Per-instance resources for a local assistant: the renderer-facing subset of
  * ports, the instance directory, and the local runtime install metadata.

package/node_modules/@vellumai/local-mode/src/lockfile.test.ts

@@ -5,8 +5,10 @@ import path from "node:path";
 
 import {
   getLockfileData,
+  isPairedLockfileEntry,
   replacePlatformAssistants,
   upsertLockfileAssistant,
+  upsertRendererLockfileAssistant,
 } from "./lockfile";
 
 let dir: string;
@@ -112,6 +114,32 @@ describe("getLockfileData", () => {
   });
 });
 
+// Hosts pass {paired} to getGuardianAccessToken so expired pairings get
+// re-pair guidance instead of hatch/wake; this pins the classification.
+describe("isPairedLockfileEntry", () => {
+  test("classifies paired cloud entries and host pairing markers as paired", () => {
+    writeOnDisk({
+      assistants: [
+        { assistantId: "paired-1", cloud: "paired" },
+        { assistantId: "paired-marker", cloud: "local", paired: true },
+        { assistantId: "local-1", cloud: "local" },
+      ],
+      activeAssistant: "local-1",
+    });
+
+    expect(isPairedLockfileEntry([lockfilePath], "paired-1")).toBe(true);
+    expect(isPairedLockfileEntry([lockfilePath], "paired-marker")).toBe(true);
+    expect(isPairedLockfileEntry([lockfilePath], "local-1")).toBe(false);
+    expect(isPairedLockfileEntry([lockfilePath], "missing")).toBe(false);
+  });
+
+  test("an absent lockfile never classifies as paired", () => {
+    expect(
+      isPairedLockfileEntry([path.join(dir, "absent.json")], "paired-1"),
+    ).toBe(false);
+  });
+});
+
 describe("upsertLockfileAssistant", () => {
   test("rejects an assistant with no id", () => {
     const result = upsertLockfileAssistant(
@@ -223,7 +251,109 @@ describe("upsertLockfileAssistant", () => {
   });
 });
 
+describe("upsertRendererLockfileAssistant", () => {
+  const paired = {
+    assistantId: "paired-1",
+    cloud: "paired",
+    paired: true,
+    runtimeUrl: "https://gateway.example.com",
+    name: "Paired assistant",
+  };
+
+  test("rejects creating or reclassifying an entry as paired", () => {
+    expect(
+      upsertRendererLockfileAssistant([lockfilePath], paired, "paired-1"),
+    ).toMatchObject({ ok: false, status: 403 });
+
+    writeOnDisk({
+      assistants: [{ assistantId: "local-1", cloud: "local" }],
+      activeAssistant: "local-1",
+    });
+    expect(
+      upsertRendererLockfileAssistant(
+        [lockfilePath],
+        {
+          assistantId: "local-1",
+          cloud: "paired",
+          runtimeUrl: "https://gateway.example.com",
+        },
+        undefined,
+      ),
+    ).toMatchObject({ ok: false, status: 403 });
+  });
+
+  test("rejects retargeting or reclassifying an existing paired entry", () => {
+    writeOnDisk({ assistants: [paired], activeAssistant: "paired-1" });
+
+    expect(
+      upsertRendererLockfileAssistant(
+        [lockfilePath],
+        { assistantId: "paired-1", runtimeUrl: "https://attacker.example.com" },
+        undefined,
+      ),
+    ).toMatchObject({ ok: false, status: 403 });
+    expect(
+      upsertRendererLockfileAssistant(
+        [lockfilePath],
+        { assistantId: "paired-1", cloud: "local" },
+        undefined,
+      ),
+    ).toMatchObject({ ok: false, status: 403 });
+    expect(readOnDisk()).toEqual({
+      assistants: [paired],
+      activeAssistant: "paired-1",
+    });
+  });
+
+  test("allows non-security updates and activation of an existing pairing", () => {
+    writeOnDisk({ assistants: [paired], activeAssistant: null });
+
+    const result = upsertRendererLockfileAssistant(
+      [lockfilePath],
+      {
+        assistantId: "paired-1",
+        cloud: "paired",
+        runtimeUrl: "https://gateway.example.com",
+        name: "Renamed pairing",
+      },
+      "paired-1",
+    );
+
+    expect(result.ok).toBe(true);
+    expect(readOnDisk()).toEqual({
+      assistants: [{ ...paired, name: "Renamed pairing" }],
+      activeAssistant: "paired-1",
+    });
+  });
+});
+
 describe("replacePlatformAssistants", () => {
+  test("rejects a renderer sync that tries to create a paired entry", () => {
+    writeOnDisk({
+      activeAssistant: "asst_local",
+      assistants: [
+        { assistantId: "asst_local", cloud: "local", runtimeUrl: "http://l" },
+      ],
+    });
+
+    expect(
+      replacePlatformAssistants([lockfilePath], [
+        {
+          assistantId: "asst_local",
+          cloud: "paired",
+          paired: true,
+          runtimeUrl: "https://attacker.example.com",
+        },
+      ]),
+    ).toMatchObject({ ok: false, status: 403 });
+    expect(readOnDisk()).toEqual({
+      activeAssistant: "asst_local",
+      assistants: [
+        { assistantId: "asst_local", cloud: "local", runtimeUrl: "http://l" },
+      ],
+    });
+  });
+
   test("replaces platform assistants while keeping local ones and unknown fields", () => {
     writeOnDisk({
       schemaVersion: 99,

package/node_modules/@vellumai/local-mode/src/lockfile.ts

@@ -1,7 +1,11 @@
 import fs from "node:fs";
 import path from "node:path";
 
-import { parseLockfile, type Lockfile } from "./lockfile-contract";
+import {
+  parseLockfile,
+  resolveCloud,
+  type Lockfile,
+} from "./lockfile-contract";
 import { stripSensitiveFields } from "./util";
 
 export type LockfileResult =
@@ -35,10 +39,77 @@ export function getLockfileData(lockfilePaths: string[]): LockfileResult {
   return { ok: true, data: parseLockfile(data) };
 }
 
+/**
+ * Whether the lockfile records this assistant as a paired entry. Paired
+ * entries have no local daemon, so guardian-token failure guidance must say
+ * re-pair rather than hatch/wake.
+ */
+export function isPairedLockfileEntry(
+  lockfilePaths: string[],
+  assistantId: string,
+): boolean {
+  const lockfile = readRawLockfile(lockfilePaths);
+  const assistants = Array.isArray(lockfile.assistants)
+    ? (lockfile.assistants as Array<Record<string, unknown>>)
+    : [];
+  return assistants.some(
+    (assistant) =>
+      assistant?.assistantId === assistantId &&
+      (resolveCloud(assistant) === "paired" || assistant.paired === true),
+  );
+}
+
 export type WriteResult =
   | { ok: true; lockfile: Lockfile }
   | { ok: false; status: number; error: string };
 
+/**
+ * Read the first parseable lockfile as raw JSON (unknown fields intact) for a
+ * read-modify-write cycle; an unreadable file yields an empty lockfile.
+ */
+export function readRawLockfile(
+  lockfilePaths: string[],
+): Record<string, unknown> {
+  for (const candidate of lockfilePaths) {
+    try {
+      return JSON.parse(fs.readFileSync(candidate, "utf-8")) as Record<
+        string,
+        unknown
+      >;
+    } catch {
+      // continue
+    }
+  }
+  return { assistants: [], activeAssistant: null };
+}
+
+/**
+ * Atomically persist a raw lockfile (write-to-temp + rename) and return the
+ * validated, sensitive-field-stripped view of what was written.
+ */
+export function writeRawLockfile(
+  lockfilePaths: string[],
+  lockfile: Record<string, unknown>,
+): WriteResult {
+  const writePath = lockfilePaths[0]!;
+  try {
+    const dir = path.dirname(writePath);
+    fs.mkdirSync(dir, { recursive: true });
+    const tmp = `${writePath}.tmp.${process.pid}`;
+    fs.writeFileSync(tmp, JSON.stringify(lockfile, null, 2));
+    fs.renameSync(tmp, writePath);
+  } catch (err) {
+    return { ok: false, status: 500, error: `Failed to write lockfile: ${err}` };
+  }
+
+  const stripped = JSON.parse(JSON.stringify(lockfile)) as Record<
+    string,
+    unknown
+  >;
+  stripSensitiveFields(stripped);
+  return { ok: true, lockfile: parseLockfile(stripped) };
+}
+
 export function upsertLockfileAssistant(
   lockfilePaths: string[],
   assistant: Record<string, unknown>,
@@ -48,16 +119,7 @@ export function upsertLockfileAssistant(
     return { ok: false, status: 400, error: "Missing assistant.assistantId" };
   }
 
-  let lockfile: Record<string, unknown> = { assistants: [], activeAssistant: null };
-  for (const candidate of lockfilePaths) {
-    try {
-      lockfile = JSON.parse(fs.readFileSync(candidate, "utf-8")) as Record<string, unknown>;
-      break;
-    } catch {
-      // continue
-    }
-  }
-
+  const lockfile = readRawLockfile(lockfilePaths);
   const assistants = Array.isArray(lockfile.assistants) ? lockfile.assistants : [];
   const existingIdx = assistants.findIndex(
     (a: Record<string, unknown>) => a?.assistantId === assistant.assistantId,
@@ -72,20 +134,53 @@ export function upsertLockfileAssistant(
     lockfile.activeAssistant = activeAssistant;
   }
 
-  const writePath = lockfilePaths[0]!;
-  try {
-    const dir = path.dirname(writePath);
-    fs.mkdirSync(dir, { recursive: true });
-    const tmp = `${writePath}.tmp.${process.pid}`;
-    fs.writeFileSync(tmp, JSON.stringify(lockfile, null, 2));
-    fs.renameSync(tmp, writePath);
-  } catch (err) {
-    return { ok: false, status: 500, error: `Failed to write lockfile: ${err}` };
+  return writeRawLockfile(lockfilePaths, lockfile);
+}
+
+const PAIRED_LOCKFILE_WRITE_ERROR =
+  "Paired assistant identity can only be changed through the connect flow";
+
+/**
+ * Apply a renderer-originated lockfile upsert without allowing it to create,
+ * retarget, or reclassify a paired assistant. Existing paired entries may
+ * still update non-security fields and become the active assistant.
+ */
+export function upsertRendererLockfileAssistant(
+  lockfilePaths: string[],
+  assistant: Record<string, unknown>,
+  activeAssistant: string | undefined,
+): WriteResult {
+  if (!assistant || typeof assistant.assistantId !== "string") {
+    return { ok: false, status: 400, error: "Missing assistant.assistantId" };
   }
 
-  const stripped = JSON.parse(JSON.stringify(lockfile)) as Record<string, unknown>;
-  stripSensitiveFields(stripped);
-  return { ok: true, lockfile: parseLockfile(stripped) };
+  const lockfile = readRawLockfile(lockfilePaths);
+  const assistants = Array.isArray(lockfile.assistants)
+    ? (lockfile.assistants as Array<Record<string, unknown>>)
+    : [];
+  const existing = assistants.find(
+    (entry) => entry?.assistantId === assistant.assistantId,
+  );
+  const merged = { ...existing, ...assistant };
+  const existingIsPaired =
+    existing != null &&
+    (resolveCloud(existing) === "paired" || existing.paired === true);
+  const mergedIsPaired =
+    resolveCloud(merged) === "paired" || merged.paired === true;
+
+  if (!existingIsPaired && mergedIsPaired) {
+    return { ok: false, status: 403, error: PAIRED_LOCKFILE_WRITE_ERROR };
+  }
+  if (
+    existingIsPaired &&
+    (resolveCloud(merged) !== "paired" ||
+      merged.runtimeUrl !== existing.runtimeUrl ||
+      merged.paired !== existing.paired)
+  ) {
+    return { ok: false, status: 403, error: PAIRED_LOCKFILE_WRITE_ERROR };
+  }
+
+  return upsertLockfileAssistant(lockfilePaths, assistant, activeAssistant);
 }
 
 export function isActiveAssistant(
@@ -115,16 +210,23 @@ export function replacePlatformAssistants(
   platformAssistants: Array<Record<string, unknown>>,
   organizationId?: string,
 ): WriteResult {
-  let lockfile: Record<string, unknown> = { assistants: [], activeAssistant: null };
-  for (const candidate of lockfilePaths) {
-    try {
-      lockfile = JSON.parse(fs.readFileSync(candidate, "utf-8")) as Record<string, unknown>;
-      break;
-    } catch {
-      // continue
-    }
+  if (
+    platformAssistants.some(
+      (assistant) =>
+        typeof assistant?.assistantId !== "string" ||
+        assistant.assistantId === "" ||
+        resolveCloud(assistant) !== "vellum" ||
+        assistant.paired === true,
+    )
+  ) {
+    return {
+      ok: false,
+      status: 403,
+      error: "Platform sync only accepts platform assistants",
+    };
   }
 
+  const lockfile = readRawLockfile(lockfilePaths);
   const existing = Array.isArray(lockfile.assistants) ? lockfile.assistants : [];
   const syncedIds = new Set(platformAssistants.map((a) => a.assistantId));
   // Org-scoped sync preserves other orgs' platform entries; no org full-replaces.
@@ -143,18 +245,5 @@ export function replacePlatformAssistants(
     if (!stillExists) lockfile.activeAssistant = null;
   }
 
-  const writePath = lockfilePaths[0]!;
-  try {
-    const dir = path.dirname(writePath);
-    fs.mkdirSync(dir, { recursive: true });
-    const tmp = `${writePath}.tmp.${process.pid}`;
-    fs.writeFileSync(tmp, JSON.stringify(lockfile, null, 2));
-    fs.renameSync(tmp, writePath);
-  } catch (err) {
-    return { ok: false, status: 500, error: `Failed to write lockfile: ${err}` };
-  }
-
-  const stripped = JSON.parse(JSON.stringify(lockfile)) as Record<string, unknown>;
-  stripSensitiveFields(stripped);
-  return { ok: true, lockfile: parseLockfile(stripped) };
+  return writeRawLockfile(lockfilePaths, lockfile);
 }