@vellumai/assistant 0.6.3 → 0.6.5

package/src/runtime/routes/backup-routes.ts

@@ -0,0 +1,519 @@
+/**
+ * Route handlers for the backup/restore endpoints.
+ *
+ * GET  /v1/backups             — list local + offsite snapshots
+ * POST /v1/backups/create      — manual snapshot trigger (bypasses schedule gates)
+ * POST /v1/backups/restore     — restore a snapshot into the workspace
+ * POST /v1/backups/verify      — verify a snapshot without restoring
+ *
+ * The list endpoint reports a per-destination `reachable` flag so callers can
+ * render offsite status (e.g. iCloud Drive enabled / external volume mounted)
+ * without probing each path themselves.
+ *
+ * Restore and verify accept a `path` pointing at a concrete snapshot file. The
+ * path must resolve (via `realpath`) to somewhere inside the configured local
+ * or offsite backup directories — this prevents a caller from coaxing the
+ * daemon into restoring an arbitrary file via a symlink escape.
+ *
+ * The backup decryption key is only loaded when the target file is a
+ * `.vbundle.enc` (encrypted) bundle. Plaintext `.vbundle` files never touch
+ * the key material, which means plaintext-only installs never create the
+ * key file as a side effect of list/restore/verify.
+ */
+
+import { promises as fs } from "node:fs";
+import { dirname, sep } from "node:path";
+
+import { z } from "zod";
+
+import { readBackupKey } from "../../backup/backup-key.js";
+import {
+  type BackupRunResult,
+  createSnapshotNow,
+} from "../../backup/backup-worker.js";
+import {
+  listSnapshotsInDir,
+  type SnapshotEntry,
+} from "../../backup/list-snapshots.js";
+import {
+  getBackupKeyPath,
+  getLocalBackupsDir,
+  resolveOffsiteDestinations,
+} from "../../backup/paths.js";
+import { restoreFromSnapshot, verifySnapshot } from "../../backup/restore.js";
+import { getConfig, invalidateConfigCache } from "../../config/loader.js";
+import type { BackupDestination } from "../../config/schema.js";
+import { getMemoryCheckpoint } from "../../memory/checkpoints.js";
+import { clearCache as clearTrustCache } from "../../permissions/trust-store.js";
+import { getLogger } from "../../util/logger.js";
+import {
+  getWorkspaceDir,
+  getWorkspaceHooksDir,
+} from "../../util/platform.js";
+import { httpError } from "../http-errors.js";
+import type { RouteDefinition } from "../http-router.js";
+import { DefaultPathResolver } from "../migrations/vbundle-import-analyzer.js";
+
+const log = getLogger("backup-routes");
+
+/** Memory checkpoint key for the last successful backup run (milliseconds). */
+const LAST_RUN_CHECKPOINT_KEY = "backup:last_run_at";
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve an absolute path via `realpath`, following symlinks. Returns `null`
+ * when the path does not exist or any component is missing. Callers that need
+ * to distinguish missing-file from other errors should check separately.
+ */
+async function safeRealpath(path: string): Promise<string | null> {
+  try {
+    return await fs.realpath(path);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check whether `candidate` is contained inside `root`. Containment is
+ * inclusive of `root` itself (so `root === candidate` is accepted) and uses
+ * the platform path separator so a root of `/a` doesn't accidentally match
+ * `/a-evil/`. Callers must pass already-realpath'd inputs.
+ */
+function isInside(candidate: string, root: string): boolean {
+  if (candidate === root) return true;
+  return candidate.startsWith(root + sep);
+}
+
+/**
+ * Build the list of absolute directories a restore/verify target is allowed
+ * to live inside. Includes the local backups directory plus every configured
+ * offsite destination (after resolving the null → iCloud default).
+ */
+function computeAllowedRoots(): string[] {
+  const config = getConfig();
+  const roots: string[] = [getLocalBackupsDir(config.backup.localDirectory)];
+  for (const dest of resolveOffsiteDestinations(
+    config.backup.offsite.destinations,
+  )) {
+    roots.push(dest.path);
+  }
+  return roots;
+}
+
+/**
+ * Resolve a caller-supplied snapshot path against the allowed roots. Returns
+ * the realpath'd candidate on success, or an `Response` error envelope if the
+ * path is missing, outside every root, or a symlink that escapes.
+ *
+ * Symlink handling: we realpath both the candidate and every root, then
+ * compare. A symlink inside an allowed root pointing at `/etc/passwd` would
+ * be caught here because `realpath(candidate)` returns `/etc/passwd` which
+ * is not inside any allowed root.
+ */
+async function validateSnapshotPath(
+  rawPath: unknown,
+): Promise<{ path: string } | { error: Response }> {
+  if (typeof rawPath !== "string" || rawPath.length === 0) {
+    return {
+      error: httpError(
+        "BAD_REQUEST",
+        "Request body must include a non-empty `path` field",
+        400,
+      ),
+    };
+  }
+
+  const realCandidate = await safeRealpath(rawPath);
+  if (realCandidate == null) {
+    return {
+      error: httpError(
+        "BAD_REQUEST",
+        `Snapshot path does not exist: ${rawPath}`,
+        400,
+      ),
+    };
+  }
+
+  const allowedRoots = computeAllowedRoots();
+  for (const root of allowedRoots) {
+    const realRoot = await safeRealpath(root);
+    if (realRoot == null) continue;
+    if (isInside(realCandidate, realRoot)) {
+      return { path: realCandidate };
+    }
+  }
+
+  return {
+    error: httpError(
+      "BAD_REQUEST",
+      "Snapshot path is outside the configured backup directories",
+      400,
+    ),
+  };
+}
+
+/**
+ * Load the backup decryption key iff the target snapshot is encrypted. Returns
+ * `{ key: null }` for plaintext bundles without touching the filesystem.
+ * Returns `{ error }` with a clear 400 envelope when an encrypted bundle is
+ * supplied but no key file exists (an unrecoverable user-facing state that
+ * should not silently 500).
+ */
+async function loadKeyIfEncrypted(
+  snapshotPath: string,
+): Promise<{ key: Buffer | null } | { error: Response }> {
+  if (!snapshotPath.endsWith(".vbundle.enc")) {
+    return { key: null };
+  }
+  const key = await readBackupKey(getBackupKeyPath());
+  if (key == null) {
+    return {
+      error: httpError(
+        "BAD_REQUEST",
+        "Encrypted snapshot requires a backup key, but backup.key is missing",
+        400,
+      ),
+    };
+  }
+  return { key };
+}
+
+// ---------------------------------------------------------------------------
+// GET /v1/backups
+// ---------------------------------------------------------------------------
+
+/**
+ * Shape returned by {@link handleBackupList}. Exported so client code (and
+ * the test suite) can type the JSON response without re-deriving it.
+ *
+ * `offsiteEnabled` distinguishes "offsite disabled" (user turned it off — the
+ * UI should hide or gray out offsite cards) from "offsite enabled but no
+ * destinations configured" (the `offsite` array is empty but the UI should
+ * still prompt the user to add one).
+ */
+export interface BackupListResponse {
+  local: SnapshotEntry[];
+  offsite: Array<{
+    destination: BackupDestination;
+    snapshots: SnapshotEntry[];
+    reachable: boolean;
+  }>;
+  offsiteEnabled: boolean;
+  nextRunAt: string | null;
+}
+
+/**
+ * List all known backup snapshots — local and every configured offsite
+ * destination — along with scheduling metadata. Per-destination `reachable`
+ * reflects whether `dirname(destination.path)` exists on disk right now (the
+ * same probe the offsite writer uses), so clients can distinguish "empty
+ * destination" from "unavailable destination" without a second round trip.
+ *
+ * When `backup.offsite.enabled` is `false`, the offsite array is returned
+ * empty without probing any destinations — mirroring the worker's runtime
+ * logic so the UI never renders offsite cards after the user has disabled
+ * offsite backups. Clients should gate offsite UI on `offsiteEnabled` rather
+ * than `offsite.length`.
+ */
+export async function handleBackupList(_req: Request): Promise<Response> {
+  try {
+    const config = getConfig();
+    const localDir = getLocalBackupsDir(config.backup.localDirectory);
+    const local = await listSnapshotsInDir(localDir);
+
+    const offsiteEnabled = config.backup.offsite.enabled;
+    const offsite: BackupListResponse["offsite"] = [];
+    if (offsiteEnabled) {
+      for (const destination of resolveOffsiteDestinations(
+        config.backup.offsite.destinations,
+      )) {
+        let reachable = false;
+        try {
+          await fs.stat(dirname(destination.path));
+          reachable = true;
+        } catch {
+          reachable = false;
+        }
+        const snapshots = reachable
+          ? await listSnapshotsInDir(destination.path)
+          : [];
+        offsite.push({ destination, snapshots, reachable });
+      }
+    }
+
+    let nextRunAt: string | null = null;
+    if (config.backup.enabled) {
+      const lastRunRaw = getMemoryCheckpoint(LAST_RUN_CHECKPOINT_KEY);
+      if (lastRunRaw != null) {
+        const lastRunMs = Number.parseInt(lastRunRaw, 10);
+        if (!Number.isNaN(lastRunMs)) {
+          const intervalMs = config.backup.intervalHours * 3600 * 1000;
+          nextRunAt = new Date(lastRunMs + intervalMs).toISOString();
+        }
+      }
+    }
+
+    const body: BackupListResponse = {
+      local,
+      offsite,
+      offsiteEnabled,
+      nextRunAt,
+    };
+    return Response.json(body);
+  } catch (err) {
+    log.error({ err }, "Failed to list backups");
+    return httpError(
+      "INTERNAL_ERROR",
+      err instanceof Error ? err.message : "Failed to list backups",
+      500,
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// POST /v1/backups/create
+// ---------------------------------------------------------------------------
+
+/**
+ * Trigger a manual backup snapshot immediately. This bypasses both the
+ * `backup.enabled` flag and the interval gate, but still honors the
+ * snapshot-in-progress mutex: a concurrent caller receives a 409.
+ *
+ * On success, returns the full `BackupRunResult` so the client can render
+ * per-destination outcomes without re-listing.
+ */
+export async function handleBackupCreate(_req: Request): Promise<Response> {
+  try {
+    const config = getConfig();
+    const result: BackupRunResult = await createSnapshotNow(
+      config.backup,
+      new Date(),
+    );
+    return Response.json(result);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    // Map the mutex rejection to 409 so clients can distinguish "try again
+    // later" from a real failure. Matches both the in-process variant
+    // (`"snapshot in progress"`) and the cross-process file-lock variant
+    // (`"snapshot in progress (locked by pid N)"`).
+    if (message.startsWith("snapshot in progress")) {
+      return httpError("CONFLICT", "A snapshot is already in progress", 409);
+    }
+    log.error({ err }, "Manual backup snapshot failed");
+    return httpError("INTERNAL_ERROR", message, 500);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// POST /v1/backups/restore
+// ---------------------------------------------------------------------------
+
+interface RestoreRequestBody {
+  path: unknown;
+}
+
+/**
+ * Restore a snapshot into the live workspace. Destructive: the underlying
+ * `commitImport` flow backs up existing files before overwriting, but callers
+ * should still treat this as an irreversible "replace the workspace" operation.
+ *
+ * Recovery sequence (mirroring `handleMigrationImport`):
+ *   1. `restoreFromSnapshot` internally calls `resetDb()` BEFORE the commit
+ *      step so the live SQLite singleton closes its handle before
+ *      `assistant.db` is overwritten. Without this, the daemon would keep a
+ *      reference to the old inode and subsequent writes could silently
+ *      corrupt the restored state.
+ *   2. `invalidateConfigCache()` and `clearTrustCache()` are called AFTER a
+ *      successful restore so the daemon re-reads the restored `config.json`
+ *      and `trust.json` from disk instead of serving stale in-process caches.
+ *
+ * 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.
+ */
+export async function handleBackupRestore(req: Request): Promise<Response> {
+  let body: RestoreRequestBody;
+  try {
+    body = (await req.json()) as RestoreRequestBody;
+  } catch {
+    return httpError(
+      "BAD_REQUEST",
+      "Request body must be valid JSON with a `path` field",
+      400,
+    );
+  }
+
+  const validated = await validateSnapshotPath(body.path);
+  if ("error" in validated) return validated.error;
+  const snapshotPath = validated.path;
+
+  const keyResult = await loadKeyIfEncrypted(snapshotPath);
+  if ("error" in keyResult) return keyResult.error;
+
+  try {
+    const pathResolver = new DefaultPathResolver(
+      getWorkspaceDir(),
+      getWorkspaceHooksDir(),
+    );
+
+    // `restoreFromSnapshot` internally calls `resetDb()` before the commit
+    // step so the live SQLite connection is closed before assistant.db is
+    // overwritten. The singleton will be lazily reopened on the next getDb()
+    // call, after the restored file is in place.
+
+    const result = await restoreFromSnapshot(snapshotPath, {
+      key: keyResult.key ?? undefined,
+      pathResolver,
+      workspaceDir: getWorkspaceDir(),
+    });
+
+    // Invalidate in-process caches so the restored settings.json and trust.json
+    // take effect without requiring a daemon restart.
+    invalidateConfigCache();
+    clearTrustCache();
+
+    return Response.json({
+      manifest: result.manifest,
+      restoredFiles: result.restoredFiles,
+    });
+  } catch (err) {
+    log.error({ err, snapshotPath }, "Snapshot restore failed");
+    return httpError(
+      "INTERNAL_ERROR",
+      err instanceof Error ? err.message : "Snapshot restore failed",
+      500,
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// POST /v1/backups/verify
+// ---------------------------------------------------------------------------
+
+interface VerifyRequestBody {
+  path: unknown;
+}
+
+/**
+ * Verify a snapshot (decrypts if needed, runs `validateVBundle`) without
+ * touching the workspace. Does not throw on validation or decryption failure
+ * — those surface as `{ valid: false, error: ... }` so callers can render a
+ * uniform status for each snapshot in a list.
+ */
+export async function handleBackupVerify(req: Request): Promise<Response> {
+  let body: VerifyRequestBody;
+  try {
+    body = (await req.json()) as VerifyRequestBody;
+  } catch {
+    return httpError(
+      "BAD_REQUEST",
+      "Request body must be valid JSON with a `path` field",
+      400,
+    );
+  }
+
+  const validated = await validateSnapshotPath(body.path);
+  if ("error" in validated) return validated.error;
+  const snapshotPath = validated.path;
+
+  const keyResult = await loadKeyIfEncrypted(snapshotPath);
+  if ("error" in keyResult) return keyResult.error;
+
+  try {
+    const result = await verifySnapshot(snapshotPath, {
+      key: keyResult.key ?? undefined,
+    });
+    return Response.json(result);
+  } catch (err) {
+    log.error({ err, snapshotPath }, "Snapshot verification failed");
+    return httpError(
+      "INTERNAL_ERROR",
+      err instanceof Error ? err.message : "Snapshot verification failed",
+      500,
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Route definitions
+// ---------------------------------------------------------------------------
+
+export function backupRouteDefinitions(): RouteDefinition[] {
+  return [
+    {
+      endpoint: "backups",
+      method: "GET",
+      summary: "List backup snapshots",
+      description:
+        "Lists local and offsite backup snapshots. Each offsite destination includes a `reachable` flag reflecting whether the backing volume is currently available. When `backup.offsite.enabled` is false the `offsite` array is empty and `offsiteEnabled` is false — clients should gate offsite UI on `offsiteEnabled` rather than `offsite.length`.",
+      tags: ["backups"],
+      responseBody: z.object({
+        local: z.array(z.unknown()),
+        offsite: z.array(
+          z.object({
+            destination: z.object({}).passthrough(),
+            snapshots: z.array(z.unknown()),
+            reachable: z.boolean(),
+          }),
+        ),
+        offsiteEnabled: z.boolean(),
+        nextRunAt: z.string().nullable(),
+      }),
+      handler: async ({ req }) => handleBackupList(req),
+    },
+    {
+      endpoint: "backups/create",
+      method: "POST",
+      summary: "Create a backup snapshot immediately",
+      description:
+        "Trigger a manual snapshot. Bypasses the enabled and interval gates, but honors the in-progress mutex — a concurrent caller receives 409.",
+      tags: ["backups"],
+      responseBody: z.object({
+        local: z.object({}).passthrough(),
+        offsite: z.array(z.unknown()),
+        durationMs: z.number(),
+      }),
+      handler: async ({ req }) => handleBackupCreate(req),
+    },
+    {
+      endpoint: "backups/restore",
+      method: "POST",
+      summary: "Restore from a backup snapshot",
+      description:
+        "Restores a snapshot into the workspace. Destructive: the underlying commit flow backs up existing files before overwriting. The daemon closes the live SQLite handle before writing and invalidates its config/trust caches afterwards. Credentials are NOT included — users re-authenticate integrations after a restore.",
+      tags: ["backups"],
+      requestBody: z.object({
+        path: z
+          .string()
+          .describe("Absolute path to the snapshot file to restore"),
+      }),
+      responseBody: z.object({
+        manifest: z.object({}).passthrough(),
+        restoredFiles: z.number(),
+      }),
+      handler: async ({ req }) => handleBackupRestore(req),
+    },
+    {
+      endpoint: "backups/verify",
+      method: "POST",
+      summary: "Verify a backup snapshot",
+      description:
+        "Validates a snapshot without restoring. Decrypts encrypted bundles to a temp file, runs the vbundle validator, and returns a pass/fail status.",
+      tags: ["backups"],
+      requestBody: z.object({
+        path: z
+          .string()
+          .describe("Absolute path to the snapshot file to verify"),
+      }),
+      responseBody: z.object({
+        valid: z.boolean(),
+        manifest: z.object({}).passthrough().optional(),
+        error: z.string().optional(),
+      }),
+      handler: async ({ req }) => handleBackupVerify(req),
+    },
+  ];
+}

package/src/runtime/routes/browser-extension-pair-routes.ts

@@ -42,7 +42,8 @@
  */
 
 import { readFileSync } from "node:fs";
-import { resolve } from "node:path";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
 
 import { findGuardianForChannel } from "../../contacts/contact-store.js";
 import { getLogger } from "../../util/logger.js";
@@ -116,19 +117,33 @@ const ALLOWLIST_CONFIG_PATH_CANDIDATES = [
   ),
 ];
 
+/**
+ * Local, user-writable override read in addition to the canonical config.
+ * Lets developers allowlist an unpacked-extension ID without committing it
+ * to the repo. File is optional — a missing file is not an error.
+ */
+const LOCAL_OVERRIDE_PATH = join(
+  homedir(),
+  ".vellum",
+  "chrome-extension-allowlist.local.json",
+);
+
 type ChromeExtensionAllowlistConfig = {
   version: number;
   allowedExtensionIds: string[];
 };
 
-function parseAllowedExtensionIds(value: unknown): string[] {
+function parseAllowedExtensionIds(
+  value: unknown,
+  opts: { allowEmpty?: boolean } = {},
+): string[] {
   if (!Array.isArray(value)) {
     throw new Error("allowedExtensionIds is not an array");
   }
   const ids = value
     .filter((id): id is string => typeof id === "string")
     .filter((id) => EXTENSION_ID_REGEX.test(id));
-  if (ids.length === 0) {
+  if (ids.length === 0 && !opts.allowEmpty) {
     throw new Error("allowedExtensionIds has no valid extension ids");
   }
   return ids;
@@ -147,42 +162,86 @@ function loadAllowedExtensionIdsFromEnv(): string[] {
   return Array.from(new Set(ids));
 }
 
+function readIdsFromFile(
+  path: string,
+  opts: { allowEmpty?: boolean } = {},
+): string[] {
+  const raw = readFileSync(path, "utf8");
+  const parsed = JSON.parse(raw) as Partial<ChromeExtensionAllowlistConfig>;
+  return parseAllowedExtensionIds(parsed.allowedExtensionIds, opts);
+}
+
 function loadAllowedExtensionOrigins(): ReadonlySet<string> {
+  const merged = new Set<string>();
   const loadErrors: string[] = [];
+
+  // 1. Canonical repo config. Try each candidate; first parse wins (the
+  //    two candidates are the same logical file resolved two ways).
+  let canonicalLoaded = false;
   for (const configPath of ALLOWLIST_CONFIG_PATH_CANDIDATES) {
     try {
-      const raw = readFileSync(configPath, "utf8");
-      const parsed = JSON.parse(raw) as Partial<ChromeExtensionAllowlistConfig>;
-      const ids = parseAllowedExtensionIds(parsed.allowedExtensionIds);
-      return new Set<string>(ids.map((id) => `chrome-extension://${id}/`));
+      for (const id of readIdsFromFile(configPath)) {
+        merged.add(`chrome-extension://${id}/`);
+      }
+      canonicalLoaded = true;
+      break;
     } catch (err) {
       const detail = err instanceof Error ? err.message : String(err);
       loadErrors.push(`${configPath}: ${detail}`);
     }
   }
 
-  // Compiled Bun binaries run from a virtual FS root (import.meta.dir is
-  // usually `/$bunfs/root`), so repo-relative config paths can disappear in
-  // packaged builds. In that case, allow a build-time injected env fallback.
-  const envIds = loadAllowedExtensionIdsFromEnv();
-  if (envIds.length > 0) {
-    return new Set<string>(envIds.map((id) => `chrome-extension://${id}/`));
+  // 2. Local override. Silently absent is fine; malformed warns but doesn't
+  //    block other sources.
+  try {
+    for (const id of readIdsFromFile(LOCAL_OVERRIDE_PATH, { allowEmpty: true })) {
+      merged.add(`chrome-extension://${id}/`);
+    }
+  } catch (err) {
+    const isMissing =
+      err instanceof Error &&
+      "code" in err &&
+      (err as NodeJS.ErrnoException).code === "ENOENT";
+    if (!isMissing) {
+      const detail = err instanceof Error ? err.message : String(err);
+      loadErrors.push(`${LOCAL_OVERRIDE_PATH}: ${detail}`);
+    }
+  }
+
+  // 3. Env-var fallback. Compiled Bun binaries run from a virtual FS root so
+  //    repo-relative config paths can disappear in packaged builds;
+  //    `clients/macos/build.sh` bakes the canonical IDs into
+  //    `VELLUM_CHROME_EXTENSION_IDS` at compile time for that case.
+  for (const id of loadAllowedExtensionIdsFromEnv()) {
+    merged.add(`chrome-extension://${id}/`);
   }
 
-  log.error(
-    {
-      allowlistConfigPathCandidates: ALLOWLIST_CONFIG_PATH_CANDIDATES,
-      loadErrors,
-    },
-    "Failed to load Chrome extension allowlist config; pairing will reject all origins",
-  );
-  return new Set<string>();
+  if (merged.size === 0) {
+    log.error(
+      {
+        canonicalCandidates: ALLOWLIST_CONFIG_PATH_CANDIDATES,
+        localOverridePath: LOCAL_OVERRIDE_PATH,
+        loadErrors,
+      },
+      "Failed to load Chrome extension allowlist from any source; pairing will reject all origins",
+    );
+  } else if (!canonicalLoaded && loadErrors.length > 0) {
+    log.warn(
+      { loadErrors },
+      "Canonical Chrome extension allowlist unreadable — using local override and/or env vars only",
+    );
+  }
+
+  return merged;
 }
 
 /**
  * Allowlist of chrome extension origins permitted to request a capability
- * token. Loaded from the canonical config at
- * `meta/browser-extension/chrome-extension-allowlist.json`.
+ * token. Merged from the canonical repo config at
+ * `meta/browser-extension/chrome-extension-allowlist.json`, an optional
+ * local override at `~/.vellum/chrome-extension-allowlist.local.json`, and
+ * the `VELLUM_CHROME_EXTENSION_IDS` env var. Cached at module load —
+ * allowlist edits require a daemon restart to take effect.
  */
 export const ALLOWED_EXTENSION_ORIGINS = loadAllowedExtensionOrigins();