@vellumai/assistant 0.6.3 → 0.6.5

package/src/backup/paths.ts

@@ -0,0 +1,226 @@
+import { homedir, userInfo } from "node:os";
+import { dirname, isAbsolute, join } from "node:path";
+
+import {
+  getBackupDirOverride,
+  getBackupKeyPathOverride,
+} from "../config/env-registry.js";
+import type { BackupDestination } from "../config/schema.js";
+import { getProtectedDir } from "../util/platform.js";
+
+/**
+ * Computes the root ~/.vellum directory without introducing a new export from
+ * `platform.ts`. `getProtectedDir()` returns `join(vellumRoot(), "protected")`,
+ * so its parent directory is the vellum root. Using `dirname(getProtectedDir())`
+ * keeps this module self-contained and avoids expanding the platform.ts surface
+ * area just for backups.
+ */
+function vellumRootFromProtected(): string {
+  return dirname(getProtectedDir());
+}
+
+/**
+ * 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 {
+  return getBackupDirOverride() ?? join(vellumRootFromProtected(), "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");
+}
+
+function safeUserInfoHomedir(): string {
+  try {
+    return userInfo().homedir;
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Returns the iCloud Drive root on macOS. This is the "safe ancestor" we use
+ * for bootstrapping the default offsite path: if this directory exists iCloud
+ * Drive is enabled and we can safely `mkdir -p` the `VellumAssistant/backups`
+ * subtree below it.
+ *
+ * Fallback chain: `process.env.HOME` → `userInfo().homedir` → `homedir()`.
+ * Reading `$HOME` at call time keeps the function honest under tests that
+ * redirect the home directory mid-process. Uses `||` (not `??`) so an
+ * empty-string `HOME` — legal in some sandboxed envs — advances to the next
+ * fallback. `homedir()` alone is insufficient because libuv's
+ * `uv_os_homedir` returns `$HOME` as-is when it's set (even to `""`) and
+ * only consults `getpwuid_r` when `HOME` is unset entirely. `userInfo()`
+ * calls `getpwuid_r` directly via `uv_os_get_passwd`, so it returns the
+ * passwd-table home regardless of `HOME`. The `userInfo()` call is guarded
+ * via `safeUserInfoHomedir()` because it throws `SystemError` when the
+ * current UID has no passwd entry (rare on macOS but possible in
+ * sandboxed/containerized envs); catching keeps the `homedir()` fallback
+ * reachable. Asserts the final result is absolute so callers downstream
+ * (`deriveSafeAncestor`, the offsite writer) never see a relative path
+ * regardless of how the home lookup resolved.
+ */
+export function getICloudDriveRoot(): string {
+  const home = process.env.HOME || safeUserInfoHomedir() || homedir();
+  const root = join(
+    home,
+    "Library",
+    "Mobile Documents",
+    "com~apple~CloudDocs",
+  );
+  if (!isAbsolute(root)) {
+    throw new Error(
+      `getICloudDriveRoot resolved to a relative path: ${root}. ` +
+        `HOME, userInfo().homedir, and homedir() all returned empty or relative values.`,
+    );
+  }
+  return root;
+}
+
+/**
+ * Returns the default offsite backups directory — the iCloud Drive path under
+ * the VellumAssistant namespace. Used when no explicit offsite destinations
+ * are configured.
+ */
+export function getDefaultOffsiteBackupsDir(): string {
+  return join(getICloudDriveRoot(), "VellumAssistant", "backups");
+}
+
+/**
+ * Derive the "safe ancestor" for an offsite destination — a directory that
+ * must already exist on disk before we are willing to create intermediate
+ * directories under it. If the ancestor exists we `mkdir -p destinationPath`;
+ * if it is missing we skip the destination (treating it as a transient
+ * unavailability like an unplugged drive or disabled iCloud Drive).
+ *
+ * Derivation rules:
+ *   - iCloud Drive subtrees (`~/Library/Mobile Documents/com~apple~CloudDocs/...`)
+ *     anchor on the iCloud Drive root. This lets the default destination
+ *     (`.../VellumAssistant/backups`) bootstrap on first run without the user
+ *     having to pre-create the `VellumAssistant` folder.
+ *   - `/Volumes/<name>/...` paths anchor on `/Volumes/<name>`, the macOS
+ *     volume mount point. An unmounted drive has no entry in `/Volumes`, so
+ *     its destination is correctly skipped rather than bootstrapped on the
+ *     root filesystem.
+ *   - Everything else falls back to `dirname(destinationPath)` — the original
+ *     conservative behavior, preserved for arbitrary user-configured paths
+ *     where we have no reliable mount signal.
+ */
+export function deriveSafeAncestor(destinationPath: string): string {
+  const iCloudRoot = getICloudDriveRoot();
+  if (
+    destinationPath === iCloudRoot ||
+    destinationPath.startsWith(`${iCloudRoot}/`)
+  ) {
+    return iCloudRoot;
+  }
+  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);
+}
+
+/**
+ * Resolves the list of offsite backup destinations from an optional config
+ * override. When `override` is `null` (the "not configured" sentinel), returns
+ * a single-element array pointing at the iCloud default with encryption
+ * enabled. When `override` is an array (including the empty array), returns it
+ * unchanged so callers never need to null-check.
+ */
+export function resolveOffsiteDestinations(
+  override?: BackupDestination[] | null,
+): BackupDestination[] {
+  if (override == null) {
+    return [{ path: getDefaultOffsiteBackupsDir(), encrypt: true }];
+  }
+  return override;
+}
+
+/**
+ * Returns the path to the backup encryption key file. By default this is
+ * `~/.vellum/protected/backup.key`, but the `VELLUM_BACKUP_KEY_PATH` env var
+ * can override it for containerized deployments where the key must live on a
+ * persistent volume.
+ */
+export function getBackupKeyPath(): string {
+  return getBackupKeyPathOverride() ?? join(getProtectedDir(), "backup.key");
+}
+
+/**
+ * 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;
+  // `new Date()` silently normalizes out-of-range calendar values (e.g. Feb 31
+  // → March 3). Verify round-trip so malformed filenames can't be accepted and
+  // reordered in retention/restore flows.
+  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/restore.ts

@@ -0,0 +1,322 @@
+/**
+ * High-level helpers for restoring and verifying backup snapshots produced
+ * by the backup pipeline.
+ *
+ * A snapshot is one of:
+ *   - A plaintext `.vbundle` file (gzipped tar — see `vbundle-builder.ts`).
+ *   - An encrypted `.vbundle.enc` file produced by `stream-crypt.encryptFile`.
+ *
+ * The encryption status is detected purely from the file extension:
+ *   - `.vbundle.enc` → encrypted (decryption key required)
+ *   - `.vbundle`     → plaintext
+ *
+ * For encrypted snapshots, this module decrypts to a temporary file under the
+ * OS temp directory, runs validation, and then either commits the import or
+ * just reports validation status. The temp file is always cleaned up — on
+ * success and on failure — via a `try { ... } finally { unlink }` block.
+ *
+ * Restore is intentionally a thin wrapper around the existing
+ * `commitImport` flow in `runtime/migrations/vbundle-importer.ts`. That
+ * function handles bundle validation, workspace clearing, per-file
+ * backup-before-overwrite, and writing files to disk.
+ *
+ * `restoreFromSnapshot` closes the live SQLite singleton via `resetDb()`
+ * immediately before the commit step so the daemon's DB handle is released
+ * before `assistant.db` is overwritten on disk. This mirrors the pattern in
+ * `handleMigrationImport` and ensures both the HTTP restore path and any
+ * in-process CLI caller get the reset for free. Tests can inject a fake via
+ * `opts.resetDbImpl`.
+ *
+ * `commitImport` does NOT invalidate cached config or clear the trust cache.
+ * Callers are responsible for:
+ *   1. Calling `invalidateConfigCache()` and `clearTrustCache()` AFTER a
+ *      successful restore so the daemon re-reads the restored `config.json`
+ *      and `trust.json` instead of serving stale in-process caches.
+ *   2. Considering a daemon restart as the simplest, most reliable recovery
+ *      path — a CLI caller should refuse to restore against a live daemon
+ *      unless explicitly forced.
+ *
+ * Credentials are intentionally excluded from backups — they live in the OS
+ * keychain / CES and are not restored by this path. Users re-authenticate
+ * integrations after a restore.
+ */
+
+import { randomUUID } from "node:crypto";
+import { readFile, unlink } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { resetDb } from "../memory/db-connection.js";
+import type { PathResolver } from "../runtime/migrations/vbundle-import-analyzer.js";
+import { commitImport } from "../runtime/migrations/vbundle-importer.js";
+import type { ManifestType } from "../runtime/migrations/vbundle-validator.js";
+import { validateVBundle } from "../runtime/migrations/vbundle-validator.js";
+import { decryptFile } from "./stream-crypt.js";
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+/**
+ * Optional injection point for the underlying commit function. Tests pass a
+ * fake here to avoid running the destructive `commitImport` flow against the
+ * live workspace. Production callers should leave this unset so the real
+ * importer is used.
+ */
+export type CommitImpl = typeof commitImport;
+
+export interface RestoreOptions {
+  /** AES-256 decryption key. Required for `.vbundle.enc` snapshots. */
+  key?: Buffer;
+  /**
+   * Resolver that maps archive paths (e.g. `workspace/config.json`) to
+   * absolute disk paths. Required by the underlying `commitImport` flow.
+   */
+  pathResolver: PathResolver;
+  /**
+   * Absolute path to the workspace directory. When set and the bundle
+   * contains `workspace/` entries, `commitImport` clears the workspace
+   * before writing to ensure an exact-match restore.
+   */
+  workspaceDir?: string;
+  /**
+   * Optional override for the underlying commit function. Tests inject a
+   * fake to avoid mutating disk; production callers should leave this unset.
+   */
+  commitImpl?: CommitImpl;
+  /**
+   * Optional override for the DB-reset hook. Invoked immediately before
+   * `commitImpl` so the live SQLite singleton is closed before
+   * `assistant.db` is overwritten. Tests inject a spy; production callers
+   * should leave this unset so the real `resetDb` is used.
+   */
+  resetDbImpl?: () => void;
+}
+
+export interface RestoreResult {
+  /** Manifest from the bundle that was restored. */
+  manifest: ManifestType;
+  /** Number of files written (or skipped) by the underlying commit. */
+  restoredFiles: number;
+}
+
+export interface VerifyOptions {
+  /** AES-256 decryption key. Required for `.vbundle.enc` snapshots. */
+  key?: Buffer;
+}
+
+export interface VerifyResult {
+  /** True iff the bundle decrypts (when applicable) and validates. */
+  valid: boolean;
+  /** Manifest from the bundle when `valid` is true. */
+  manifest?: ManifestType;
+  /**
+   * Human-readable error message when `valid` is false. Populated for
+   * validation failures, decryption failures, and missing-file errors.
+   * Always undefined when `valid` is true.
+   */
+  error?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/** Returns true if the snapshot path indicates an encrypted bundle. */
+function isEncryptedSnapshot(snapshotPath: string): boolean {
+  return snapshotPath.endsWith(".vbundle.enc");
+}
+
+/** Build a unique temp path for a decrypted bundle. */
+function makeDecryptedTempPath(): string {
+  return join(tmpdir(), `vellum-restore-${randomUUID()}.vbundle`);
+}
+
+/**
+ * Resolve `snapshotPath` to a path that holds plaintext `.vbundle` bytes.
+ *
+ * For plaintext snapshots, this just returns `{ path: snapshotPath }`. For
+ * encrypted snapshots, it decrypts to a fresh temp file and returns
+ * `{ path: tmpPath, tmpPath }` so the caller can clean up afterwards.
+ *
+ * Throws when an encrypted bundle has no key, when `decryptFile` fails
+ * (bad key, tampered ciphertext, truncated file), or on any I/O error.
+ */
+async function materializePlaintext(
+  snapshotPath: string,
+  key: Buffer | undefined,
+): Promise<{ path: string; tmpPath: string | null }> {
+  if (!isEncryptedSnapshot(snapshotPath)) {
+    return { path: snapshotPath, tmpPath: null };
+  }
+
+  if (!key) {
+    throw new Error("Encrypted snapshot requires a decryption key");
+  }
+
+  const tmpPath = makeDecryptedTempPath();
+  await decryptFile(snapshotPath, tmpPath, key);
+  return { path: tmpPath, tmpPath };
+}
+
+/** Best-effort temp file cleanup — swallows ENOENT and other errors. */
+async function safeUnlink(path: string | null): Promise<void> {
+  if (!path) return;
+  try {
+    await unlink(path);
+  } catch {
+    // Best-effort — temp file may already be gone.
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Restore a backup snapshot into the workspace.
+ *
+ * Auto-detects encryption from the file extension. Encrypted snapshots
+ * (`.vbundle.enc`) decrypt to a temp file under `tmpdir()` before
+ * validation; the temp file is unlinked in a `finally` block so it never
+ * lingers, even on validation or commit failure.
+ *
+ * The actual restore is delegated to `commitImport`, which owns the
+ * backup-before-overwrite, workspace-clearing, and integrity-check logic.
+ * Tests can pass `opts.commitImpl` to substitute a fake without mutating
+ * the live workspace.
+ */
+export async function restoreFromSnapshot(
+  snapshotPath: string,
+  opts: RestoreOptions,
+): Promise<RestoreResult> {
+  const {
+    key,
+    pathResolver,
+    workspaceDir,
+    commitImpl = commitImport,
+    resetDbImpl = resetDb,
+  } = opts;
+
+  let tmpPath: string | null = null;
+  try {
+    const materialized = await materializePlaintext(snapshotPath, key);
+    tmpPath = materialized.tmpPath;
+
+    // Read plaintext bytes for validation + commit. validateVBundle takes
+    // raw bytes (Uint8Array) — file paths are not part of its API.
+    const fileData = await readFile(materialized.path);
+
+    const validation = validateVBundle(fileData);
+    if (!validation.is_valid || !validation.manifest || !validation.entries) {
+      const summary = validation.errors
+        .map((e) => `${e.code}: ${e.message}`)
+        .join("; ");
+      throw new Error(`Snapshot failed validation: ${summary}`);
+    }
+
+    // Close the live SQLite singleton before overwriting assistant.db on
+    // disk — otherwise the daemon keeps a handle to the old inode and
+    // subsequent writes can corrupt the restored state. Mirrors the
+    // pattern in `handleMigrationImport`. The singleton will be lazily
+    // reopened on the next getDb() call.
+    resetDbImpl();
+
+    const commitResult = commitImpl({
+      archiveData: fileData,
+      pathResolver,
+      preValidatedManifest: validation.manifest,
+      preValidatedEntries: validation.entries,
+      workspaceDir,
+    });
+
+    if (!commitResult.ok) {
+      // Surface a single error message regardless of which discriminated
+      // branch failed — callers in the backup CLI just want a message.
+      let message: string;
+      switch (commitResult.reason) {
+        case "validation_failed":
+          message = commitResult.errors
+            .map((e) => `${e.code}: ${e.message}`)
+            .join("; ");
+          break;
+        case "extraction_failed":
+        case "write_failed":
+          message = commitResult.message;
+          break;
+      }
+      throw new Error(`Snapshot restore failed: ${message}`);
+    }
+
+    return {
+      manifest: commitResult.report.manifest,
+      restoredFiles: commitResult.report.summary.total_files,
+    };
+  } finally {
+    await safeUnlink(tmpPath);
+  }
+}
+
+/**
+ * Verify a backup snapshot without restoring it.
+ *
+ * Auto-detects encryption from the file extension and decrypts to a temp
+ * file when needed (cleaned up in a `finally` block). Runs the same
+ * `validateVBundle` checks the importer would run, but never touches the
+ * workspace.
+ *
+ * Does NOT throw on validation or decryption failure — those are returned
+ * as `{ valid: false, error: ... }`. Only the missing-key precondition
+ * for encrypted bundles throws, since that is a programmer error.
+ */
+export async function verifySnapshot(
+  snapshotPath: string,
+  opts: VerifyOptions,
+): Promise<VerifyResult> {
+  const { key } = opts;
+
+  // Encrypted bundles must have a key — this is a precondition error,
+  // not a validation failure, so we throw rather than return.
+  if (isEncryptedSnapshot(snapshotPath) && !key) {
+    throw new Error("Encrypted snapshot requires a decryption key");
+  }
+
+  let tmpPath: string | null = null;
+  try {
+    let plaintextPath: string;
+    try {
+      const materialized = await materializePlaintext(snapshotPath, key);
+      tmpPath = materialized.tmpPath;
+      plaintextPath = materialized.path;
+    } catch (err) {
+      // Decryption / I/O failure — surface as a soft error so verification
+      // callers (e.g. snapshot list health checks) get a uniform shape.
+      return {
+        valid: false,
+        error: err instanceof Error ? err.message : String(err),
+      };
+    }
+
+    let fileData: Uint8Array;
+    try {
+      fileData = await readFile(plaintextPath);
+    } catch (err) {
+      return {
+        valid: false,
+        error: err instanceof Error ? err.message : String(err),
+      };
+    }
+
+    const validation = validateVBundle(fileData);
+    if (!validation.is_valid || !validation.manifest) {
+      const summary = validation.errors
+        .map((e) => `${e.code}: ${e.message}`)
+        .join("; ");
+      return { valid: false, error: summary };
+    }
+
+    return { valid: true, manifest: validation.manifest };
+  } finally {
+    await safeUnlink(tmpPath);
+  }
+}