@vellumai/vellum-gateway 0.7.0 → 0.7.2

package/src/backup/offsite-writer.ts

@@ -0,0 +1,182 @@
+/**
+ * Offsite snapshot writer with per-destination encryption.
+ *
+ * "Offsite" destinations are any location outside the local backup directory
+ * where the user wants a redundant copy. Canonical examples: iCloud Drive,
+ * an external SSD, a network share.
+ *
+ * Per-destination `encrypt` flag:
+ * - `encrypt: true`  → AES-256-GCM stream-encrypt into `.vbundle.enc`.
+ * - `encrypt: false` → plaintext copy into `.vbundle`.
+ *
+ * Each destination is written independently and sequentially.
+ */
+
+import { copyFile, mkdir, rename, stat, unlink } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+import type { SnapshotEntry } from "./list-snapshots.js";
+import { pruneDir } from "./list-snapshots.js";
+import { formatBackupFilename } from "./paths.js";
+import { encryptFile } from "./stream-crypt.js";
+
+export interface BackupDestination {
+  path: string;
+  encrypt: boolean;
+}
+
+export interface OffsiteWriteResult {
+  destination: BackupDestination;
+  entry: SnapshotEntry | null;
+  skipped?: "parent-missing";
+  error?: string;
+}
+
+/**
+ * Derive the "safe ancestor" for an offsite destination — a directory that
+ * must already exist on disk before we create intermediate directories
+ * under it.
+ */
+function deriveSafeAncestor(destinationPath: string): string {
+  // iCloud Drive subtrees anchor on the iCloud root
+  const home = process.env.HOME || "";
+  if (home) {
+    const iCloudRoot = join(home, "Library", "Mobile Documents", "com~apple~CloudDocs");
+    if (
+      destinationPath === iCloudRoot ||
+      destinationPath.startsWith(`${iCloudRoot}/`)
+    ) {
+      return iCloudRoot;
+    }
+  }
+  // /Volumes/<name>/... paths anchor on the volume mount point
+  const volumesPrefix = "/Volumes/";
+  if (destinationPath.startsWith(volumesPrefix)) {
+    const rest = destinationPath.slice(volumesPrefix.length);
+    const slash = rest.indexOf("/");
+    const volumeName = slash === -1 ? rest : rest.slice(0, slash);
+    if (volumeName.length > 0) {
+      return `${volumesPrefix}${volumeName}`;
+    }
+  }
+  return dirname(destinationPath);
+}
+
+/**
+ * Write a local snapshot to a single offsite destination.
+ */
+export async function writeOffsiteSnapshotToOne(
+  localSnapshotPath: string,
+  destination: BackupDestination,
+  key: Buffer | null,
+  now: Date,
+): Promise<OffsiteWriteResult> {
+  try {
+    try {
+      await stat(deriveSafeAncestor(destination.path));
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+        return { destination, entry: null, skipped: "parent-missing" };
+      }
+      throw err;
+    }
+
+    await mkdir(destination.path, { recursive: true, mode: 0o700 });
+
+    const filename = formatBackupFilename(now, {
+      encrypted: destination.encrypt,
+    });
+    const outputPath = join(destination.path, filename);
+
+    if (destination.encrypt) {
+      if (key == null) {
+        throw new Error(
+          "Offsite destination requires encryption but no key was provided",
+        );
+      }
+      await encryptFile(localSnapshotPath, outputPath, key);
+    } else {
+      const tempPath = `${outputPath}.tmp`;
+      await copyFile(localSnapshotPath, tempPath);
+      try {
+        await rename(tempPath, outputPath);
+      } catch (err) {
+        if ((err as NodeJS.ErrnoException).code === "EXDEV") {
+          await copyFile(tempPath, outputPath);
+          await unlink(tempPath);
+        } else {
+          throw err;
+        }
+      }
+    }
+
+    const stats = await stat(outputPath);
+    return {
+      destination,
+      entry: {
+        path: outputPath,
+        filename,
+        createdAt: now,
+        sizeBytes: stats.size,
+        encrypted: destination.encrypt,
+      },
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { destination, entry: null, error: message };
+  }
+}
+
+/**
+ * Write a local snapshot to every configured offsite destination.
+ */
+export async function writeOffsiteSnapshotToAll(
+  localSnapshotPath: string,
+  destinations: BackupDestination[],
+  key: Buffer | null,
+  now: Date,
+): Promise<OffsiteWriteResult[]> {
+  if (destinations.length === 0) return [];
+
+  const results: OffsiteWriteResult[] = [];
+  for (const destination of destinations) {
+    const result = await writeOffsiteSnapshotToOne(
+      localSnapshotPath,
+      destination,
+      key,
+      now,
+    );
+    results.push(result);
+  }
+  return results;
+}
+
+/**
+ * Apply retention to every configured offsite destination.
+ */
+export async function pruneOffsiteSnapshotsInAll(
+  destinations: BackupDestination[],
+  retention: number,
+): Promise<
+  Array<{
+    destination: BackupDestination;
+    kept: SnapshotEntry[];
+    deleted: SnapshotEntry[];
+    skipped?: boolean;
+  }>
+> {
+  const results: Array<{
+    destination: BackupDestination;
+    kept: SnapshotEntry[];
+    deleted: SnapshotEntry[];
+    skipped?: boolean;
+  }> = [];
+  for (const destination of destinations) {
+    const { kept, deleted, skipped } = await pruneDir(
+      destination.path,
+      retention,
+    );
+    results.push({ destination, kept, deleted, skipped });
+  }
+  return results;
+}

package/src/backup/paths.ts

@@ -0,0 +1,123 @@
+/**
+ * Path and filename helpers for the gateway backup module.
+ *
+ * The backup key lives in GATEWAY_SECURITY_DIR — outside the workspace
+ * and outside the assistant sandbox boundary. The assistant process never
+ * has access to this file.
+ */
+
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import { getGatewaySecurityDir } from "../paths.js";
+
+// ---------------------------------------------------------------------------
+// Key path
+// ---------------------------------------------------------------------------
+
+/** Filename for the backup encryption key inside GATEWAY_SECURITY_DIR. */
+const BACKUP_KEY_FILENAME = "backup.key";
+
+/**
+ * Returns the path to the backup encryption key file.
+ *
+ * The key lives in the gateway security directory, which is:
+ * - In Docker: a dedicated volume at /gateway-security (GATEWAY_SECURITY_DIR)
+ * - Locally: ~/.vellum/protected/
+ *
+ * This keeps the key outside the workspace — the assistant's sandbox
+ * boundary — so model-driven tools (file_read, shell) cannot access it.
+ */
+export function getBackupKeyPath(): string {
+  return join(getGatewaySecurityDir(), BACKUP_KEY_FILENAME);
+}
+
+// ---------------------------------------------------------------------------
+// Backup root + local directory
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns the backup root directory. Respects the `VELLUM_BACKUP_DIR`
+ * environment variable override (used in containerized deployments where
+ * backups must be on a persistent volume); falls back to `~/.vellum/backups`.
+ */
+export function getBackupRootDir(): string {
+  const override = process.env.VELLUM_BACKUP_DIR?.trim();
+  return override || join(homedir(), ".vellum", "backups");
+}
+
+/**
+ * Returns the directory for local (on-device) backups. By default this lives
+ * under `~/.vellum/backups/local`; callers can pass an explicit override from
+ * config to place backups elsewhere on disk.
+ */
+export function getLocalBackupsDir(override?: string | null): string {
+  return override ?? join(getBackupRootDir(), "local");
+}
+
+// ---------------------------------------------------------------------------
+// Backup filenames
+// ---------------------------------------------------------------------------
+
+/**
+ * Formats a backup filename from a date. Encrypted backups get a `.vbundle.enc`
+ * suffix; plaintext backups get `.vbundle`. Timestamp components are in UTC to
+ * avoid timezone-induced filename collisions across devices. Milliseconds are
+ * included so two backups started in the same UTC second produce distinct
+ * filenames rather than silently overwriting each other.
+ *
+ * Example: `backup-20260411-153045-123.vbundle`
+ */
+export function formatBackupFilename(
+  date: Date,
+  { encrypted }: { encrypted: boolean },
+): string {
+  const year = date.getUTCFullYear().toString().padStart(4, "0");
+  const month = (date.getUTCMonth() + 1).toString().padStart(2, "0");
+  const day = date.getUTCDate().toString().padStart(2, "0");
+  const hour = date.getUTCHours().toString().padStart(2, "0");
+  const minute = date.getUTCMinutes().toString().padStart(2, "0");
+  const second = date.getUTCSeconds().toString().padStart(2, "0");
+  const millis = date.getUTCMilliseconds().toString().padStart(3, "0");
+  const ext = encrypted ? ".vbundle.enc" : ".vbundle";
+  return `backup-${year}${month}${day}-${hour}${minute}${second}-${millis}${ext}`;
+}
+
+// Matches `backup-YYYYMMDD-HHMMSS` with an optional `-SSS` milliseconds
+// segment (legacy backups written before ms precision was added omit it) and
+// an optional `-<hex>` collision suffix that `writeLocalSnapshot` appends when
+// the canonical name is already taken. Followed by `.vbundle` or
+// `.vbundle.enc`. Kept as a module-level constant so repeated parsing doesn't
+// rebuild the RegExp.
+const BACKUP_FILENAME_RE =
+  /^backup-(\d{4})(\d{2})(\d{2})-(\d{2})(\d{2})(\d{2})(?:-(\d{3})(?:-[0-9a-f]+)?)?\.vbundle(?:\.enc)?$/;
+
+/**
+ * Inverse of `formatBackupFilename`. Parses a backup filename (with either
+ * `.vbundle` or `.vbundle.enc` suffix) and returns the encoded UTC timestamp.
+ * Accepts legacy filenames without the `-SSS` milliseconds segment (treated
+ * as `.000`). Returns `null` when the filename doesn't match the expected
+ * pattern, when a component is out of range, or when the parsed date is
+ * invalid.
+ */
+export function parseBackupTimestamp(filename: string): Date | null {
+  const match = BACKUP_FILENAME_RE.exec(filename);
+  if (!match) return null;
+  const [, year, month, day, hour, minute, second, millis] = match;
+  const ms = millis ?? "000";
+  const iso = `${year}-${month}-${day}T${hour}:${minute}:${second}.${ms}Z`;
+  const date = new Date(iso);
+  if (Number.isNaN(date.getTime())) return null;
+  if (
+    date.getUTCFullYear() !== Number(year) ||
+    date.getUTCMonth() !== Number(month) - 1 ||
+    date.getUTCDate() !== Number(day) ||
+    date.getUTCHours() !== Number(hour) ||
+    date.getUTCMinutes() !== Number(minute) ||
+    date.getUTCSeconds() !== Number(second) ||
+    date.getUTCMilliseconds() !== Number(ms)
+  ) {
+    return null;
+  }
+  return date;
+}

package/src/backup/stream-crypt.ts

@@ -0,0 +1,258 @@
+/**
+ * Streaming AES-256-GCM file encryption/decryption for backup bundles.
+ *
+ * The on-disk format is:
+ *
+ *   [12-byte IV][ciphertext...][16-byte GCM auth tag]
+ *
+ * Both encrypt and decrypt use Node streams so peak memory stays bounded
+ * regardless of input size. This is important for backup archives which may
+ * run to many gigabytes on larger workspaces.
+ *
+ * The key must be exactly 32 bytes (AES-256). The IV is randomly generated
+ * per call, which is required for GCM semantic security — never reuse an
+ * IV with the same key.
+ */
+
+import {
+  createCipheriv,
+  createDecipheriv,
+  randomBytes,
+} from "node:crypto";
+import {
+  createReadStream,
+  createWriteStream,
+} from "node:fs";
+import { open, rename, stat, unlink } from "node:fs/promises";
+import { Readable, Writable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Size of the AES-GCM initialization vector prefix, in bytes. */
+export const ENCRYPTED_HEADER_SIZE = 12;
+
+/** Size of the AES-GCM authentication tag suffix, in bytes. */
+export const GCM_TAG_SIZE = 16;
+
+const ALGORITHM = "aes-256-gcm";
+const KEY_LENGTH = 32;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function assertKey(key: Buffer): void {
+  if (key.length !== KEY_LENGTH) {
+    throw new Error("Backup encryption key must be 32 bytes");
+  }
+}
+
+async function safeUnlink(path: string): Promise<void> {
+  try {
+    await unlink(path);
+  } catch {
+    // best-effort cleanup — swallow ENOENT and other errors
+  }
+}
+
+function tempPath(outputPath: string): string {
+  return `${outputPath}.tmp.${process.pid}.${randomBytes(4).toString("hex")}`;
+}
+
+// ---------------------------------------------------------------------------
+// Encrypt
+// ---------------------------------------------------------------------------
+
+/**
+ * Stream-encrypt `inputPath` to `outputPath` using AES-256-GCM.
+ *
+ * Produces `[IV (12 bytes)][ciphertext][auth tag (16 bytes)]` in the output.
+ * Writes to a temp file and atomically renames on success; unlinks the temp
+ * file on any error so failed writes don't leave partial bundles behind.
+ */
+export async function encryptFile(
+  inputPath: string,
+  outputPath: string,
+  key: Buffer,
+): Promise<void> {
+  assertKey(key);
+
+  const iv = randomBytes(ENCRYPTED_HEADER_SIZE);
+  const cipher = createCipheriv(ALGORITHM, key, iv);
+
+  const tmp = tempPath(outputPath);
+  const writeStream = createWriteStream(tmp);
+
+  try {
+    // Write IV first so decrypt can read it without knowing the ciphertext size.
+    await new Promise<void>((resolve, reject) => {
+      writeStream.write(iv, (err) => (err ? reject(err) : resolve()));
+    });
+
+    // Stream plaintext through the cipher into the output.
+    const readStream = createReadStream(inputPath);
+    await pipeline(readStream, cipher, writeStream, { end: false });
+
+    // Append the auth tag after the ciphertext body.
+    const tag = cipher.getAuthTag();
+    await new Promise<void>((resolve, reject) => {
+      writeStream.write(tag, (err) => (err ? reject(err) : resolve()));
+    });
+
+    await new Promise<void>((resolve, reject) => {
+      writeStream.end((err?: Error | null) => (err ? reject(err) : resolve()));
+    });
+
+    await rename(tmp, outputPath);
+  } catch (err) {
+    // Make sure the write stream is closed before we try to unlink the temp file.
+    writeStream.destroy();
+    await safeUnlink(tmp);
+    throw err;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Decrypt
+// ---------------------------------------------------------------------------
+
+/**
+ * Stream-decrypt `inputPath` to `outputPath`. Expects the on-disk format
+ * produced by `encryptFile`: `[IV][ciphertext][auth tag]`.
+ *
+ * Reads the IV and auth tag via positional reads, then streams only the
+ * ciphertext body through the decipher. Atomic tmp + rename semantics.
+ */
+export async function decryptFile(
+  inputPath: string,
+  outputPath: string,
+  key: Buffer,
+): Promise<void> {
+  assertKey(key);
+
+  const info = await stat(inputPath);
+  const totalSize = info.size;
+  const minSize = ENCRYPTED_HEADER_SIZE + GCM_TAG_SIZE;
+  if (totalSize < minSize) {
+    throw new Error(
+      `Encrypted file is too small: ${totalSize} bytes (need at least ${minSize})`,
+    );
+  }
+
+  // Read IV (first 12 bytes) and auth tag (last 16 bytes) via positional reads.
+  const iv = Buffer.alloc(ENCRYPTED_HEADER_SIZE);
+  const tag = Buffer.alloc(GCM_TAG_SIZE);
+  const fh = await open(inputPath, "r");
+  try {
+    await fh.read(iv, 0, ENCRYPTED_HEADER_SIZE, 0);
+    await fh.read(tag, 0, GCM_TAG_SIZE, totalSize - GCM_TAG_SIZE);
+  } finally {
+    await fh.close();
+  }
+
+  const decipher = createDecipheriv(ALGORITHM, key, iv);
+  decipher.setAuthTag(tag);
+
+  const ciphertextStart = ENCRYPTED_HEADER_SIZE;
+  const ciphertextEnd = totalSize - GCM_TAG_SIZE - 1; // createReadStream end is inclusive
+  const hasCiphertext = ciphertextEnd >= ciphertextStart;
+
+  const tmp = tempPath(outputPath);
+  const writeStream = createWriteStream(tmp);
+
+  try {
+    const ciphertextStream = hasCiphertext
+      ? createReadStream(inputPath, {
+          start: ciphertextStart,
+          end: ciphertextEnd,
+        })
+      : Readable.from([]);
+
+    // pipeline consumes the ciphertext, pushes it through the decipher, and
+    // calls decipher.final() at the end — which is where auth tag verification
+    // happens. A bad tag surfaces here as a thrown error.
+    await pipeline(ciphertextStream, decipher, writeStream);
+
+    await rename(tmp, outputPath);
+  } catch (err) {
+    writeStream.destroy();
+    await safeUnlink(tmp);
+    throw err;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Verify
+// ---------------------------------------------------------------------------
+
+/**
+ * Verify that `path` is a valid AES-256-GCM encrypted bundle for `key`.
+ *
+ * Streams the ciphertext through the decipher into a null sink and relies on
+ * `decipher.final()` to either succeed (tag matches) or throw (tamper / wrong
+ * key). No scratch file is written, so a full or read-only tmpdir cannot
+ * cause a healthy backup to be reported as invalid.
+ *
+ * Returns `true` if the bundle authenticates, `false` on a cryptographic
+ * failure (bad auth tag, wrong key, truncated/short input). Filesystem errors
+ * on the *source* file (ENOENT, EACCES, EIO, …) are rethrown so callers can
+ * distinguish tamper from transient I/O.
+ */
+export async function verifyEncryptedFile(
+  path: string,
+  key: Buffer,
+): Promise<boolean> {
+  assertKey(key);
+
+  const info = await stat(path);
+  const totalSize = info.size;
+  const minSize = ENCRYPTED_HEADER_SIZE + GCM_TAG_SIZE;
+  if (totalSize < minSize) {
+    return false;
+  }
+
+  const iv = Buffer.alloc(ENCRYPTED_HEADER_SIZE);
+  const tag = Buffer.alloc(GCM_TAG_SIZE);
+  const fh = await open(path, "r");
+  try {
+    await fh.read(iv, 0, ENCRYPTED_HEADER_SIZE, 0);
+    await fh.read(tag, 0, GCM_TAG_SIZE, totalSize - GCM_TAG_SIZE);
+  } finally {
+    await fh.close();
+  }
+
+  const decipher = createDecipheriv(ALGORITHM, key, iv);
+  decipher.setAuthTag(tag);
+
+  const ciphertextStart = ENCRYPTED_HEADER_SIZE;
+  const ciphertextEnd = totalSize - GCM_TAG_SIZE - 1;
+  const hasCiphertext = ciphertextEnd >= ciphertextStart;
+  const ciphertextStream = hasCiphertext
+    ? createReadStream(path, { start: ciphertextStart, end: ciphertextEnd })
+    : Readable.from([]);
+
+  const nullSink = new Writable({
+    write(_chunk, _encoding, cb) {
+      cb();
+    },
+  });
+
+  try {
+    await pipeline(ciphertextStream, decipher, nullSink);
+    return true;
+  } catch (err) {
+    if (isFilesystemError(err)) {
+      throw err;
+    }
+    return false;
+  }
+}
+
+function isFilesystemError(err: unknown): boolean {
+  if (!err || typeof err !== "object") return false;
+  const code = (err as { code?: unknown }).code;
+  return typeof code === "string" && /^E[A-Z]+$/.test(code);
+}

package/src/chrome-extension-origins.ts

@@ -0,0 +1,28 @@
+/**
+ * Allowlist of known Vellum Chrome extension origins.
+ *
+ * Chrome extension IDs are deterministic per environment: non-production
+ * builds embed a fixed public key in the manifest (injected at build time by
+ * `clients/chrome-extension/build.sh`), and the production build uses the
+ * stable Chrome Web Store signing key. All four IDs are therefore stable and
+ * enumerable — no need for a catch-all regex.
+ *
+ * The canonical mapping of env → extensionId lives in:
+ *   clients/chrome-extension/extension-environments.json
+ *
+ * If a new environment is added or an ID changes, update both files.
+ *
+ * Format: `chrome-extension://<id>` (the value of the HTTP Origin header sent
+ * by the extension's service worker when it makes cross-origin requests to the
+ * local gateway).
+ */
+export const KNOWN_EXTENSION_ORIGINS: ReadonlySet<string> = new Set([
+  // production (Chrome Web Store)
+  "chrome-extension://hphbdmpffeigpcdjkckleobjmhhokpne",
+  // dev
+  "chrome-extension://kajfcoaefacmjgdaloeafnpcfaeahcio",
+  // staging
+  "chrome-extension://idpcnibfinmkdhlpenkglianflkbhfim",
+  // local
+  "chrome-extension://gfcldmjjhcginboeldmknclbjilohcbn",
+]);

package/src/cli/enable-proxy.ts

@@ -23,7 +23,6 @@ try {
 }
 
 const gateway = (config.gateway ?? {}) as Record<string, unknown>;
-gateway.runtimeProxyEnabled = true;
 gateway.runtimeProxyRequireAuth = false;
 gateway.unmappedPolicy = "default";
 gateway.defaultAssistantId = "self";

package/src/config-file-cache.ts

@@ -6,9 +6,7 @@
  * is passed to a getter, or when `refreshNow()` is called explicitly.
  */
 
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-import { getWorkspaceDir } from "./credential-reader.js";
+import { readConfigFileOrEmpty } from "./config-file-utils.js";
 
 const DEFAULT_TTL_MS = 1000;
 
@@ -16,18 +14,6 @@ type ReadOptions = {
   force?: boolean;
 };
 
-function readConfigFile(path: string): Record<string, unknown> {
-  try {
-    if (!existsSync(path)) return {};
-    const raw = readFileSync(path, "utf-8");
-    const data = JSON.parse(raw);
-    if (!data || typeof data !== "object" || Array.isArray(data)) return {};
-    return data as Record<string, unknown>;
-  } catch {
-    return {};
-  }
-}
-
 /**
  * Iterate entries and keep only those whose value is a non-empty,
  * non-whitespace string. Returns undefined when the input is not
@@ -48,21 +34,19 @@ function normalizeRecord(raw: unknown): Record<string, string> | undefined {
 
 export class ConfigFileCache {
   private ttlMs: number;
-  private configPath: string;
   private snapshot: Record<string, unknown> = {};
   private lastReadAt = 0;
   private invalidateCallbacks: Set<() => void> = new Set();
 
   constructor(opts?: { ttlMs?: number }) {
     this.ttlMs = opts?.ttlMs ?? DEFAULT_TTL_MS;
-    this.configPath = join(getWorkspaceDir(), "config.json");
   }
 
   /** Read the config file if the cached snapshot is stale or force is set. */
   private ensureFresh(opts?: ReadOptions): void {
     const now = Date.now();
     if (opts?.force || now - this.lastReadAt >= this.ttlMs) {
-      this.snapshot = readConfigFile(this.configPath);
+      this.snapshot = readConfigFileOrEmpty();
       this.lastReadAt = Date.now();
     }
   }
@@ -121,7 +105,7 @@ export class ConfigFileCache {
 
   /** Immediately re-read config.json, updating the cached snapshot. */
   refreshNow(): void {
-    this.snapshot = readConfigFile(this.configPath);
+    this.snapshot = readConfigFileOrEmpty();
     this.lastReadAt = Date.now();
   }