@vellumai/assistant 0.7.1 → 0.7.2

package/src/runtime/migrations/vbundle-import-policy.ts

@@ -0,0 +1,172 @@
+/**
+ * Shared invariants and predicate functions consumed by both the buffer-
+ * based `commitImport` and the streaming `streamCommitImport`. These
+ * decisions must stay in lockstep across both importers — moving them
+ * here removes the parallel-implementation skew risk that would otherwise
+ * grow as either importer evolves.
+ *
+ * Pure: no `node:fs`, no I/O, no async. Functions over strings + manifest
+ * data shapes only.
+ */
+
+export const LEGACY_USER_MD_ARCHIVE_PATH = "prompts/USER.md";
+
+export const CONFIG_ARCHIVE_PATHS: ReadonlySet<string> = new Set([
+  "workspace/config.json",
+  "config/settings.json",
+]);
+
+export const CREDENTIAL_METADATA_ARCHIVE_PATH =
+  "workspace/data/credentials/metadata.json";
+
+export const WORKSPACE_PRESERVE_PATHS: readonly string[] = [
+  "embedding-models",
+  "deprecated",
+  "data/db",
+  "data/qdrant",
+];
+
+export function isWorkspaceNamespacedArchivePath(archivePath: string): boolean {
+  return archivePath.startsWith("workspace/");
+}
+
+export function isLegacyPersonaArchivePath(archivePath: string): boolean {
+  return archivePath === LEGACY_USER_MD_ARCHIVE_PATH;
+}
+
+export function isConfigArchivePath(archivePath: string): boolean {
+  return CONFIG_ARCHIVE_PATHS.has(archivePath);
+}
+
+export function isCredentialMetadataArchivePath(archivePath: string): boolean {
+  return archivePath === CREDENTIAL_METADATA_ARCHIVE_PATH;
+}
+
+/**
+ * Partition `WORKSPACE_PRESERVE_PATHS` into the two skip sets the buffer
+ * importer's selective-clear loop consumes:
+ *
+ * - `topLevelSkipDirs`: single-segment preserve-paths (e.g. "embedding-models").
+ * - `dataSubdirSkipDirs`: second segment of `data/<x>` preserve-paths
+ *   (e.g. "db" for "data/db").
+ *
+ * Stays in sync with WORKSPACE_PRESERVE_PATHS automatically — adding a
+ * new entry of either shape doesn't require touching the buffer importer.
+ * Multi-segment paths outside the `data/` subtree are intentionally
+ * unsupported here; the buffer importer's walk doesn't recurse into
+ * arbitrary subdirs. If a future preserve-path needs deeper coverage,
+ * widen this helper and the buffer importer's walk together.
+ */
+export function partitionWorkspacePreserveSkipDirs(): {
+  topLevelSkipDirs: ReadonlySet<string>;
+  dataSubdirSkipDirs: ReadonlySet<string>;
+} {
+  const topLevelSkipDirs = new Set<string>();
+  const dataSubdirSkipDirs = new Set<string>();
+  for (const rel of WORKSPACE_PRESERVE_PATHS) {
+    const parts = rel.split("/");
+    if (parts.length === 1) {
+      topLevelSkipDirs.add(parts[0]!);
+    } else if (parts.length === 2 && parts[0] === "data") {
+      dataSubdirSkipDirs.add(parts[1]!);
+    }
+  }
+  return { topLevelSkipDirs, dataSubdirSkipDirs };
+}
+
+export const LEGACY_RUNTIME_VERSION_SENTINEL = "0.0.0-legacy";
+
+type SemverTriple = readonly [number, number, number];
+
+function parseSemverTriple(version: string): SemverTriple | null {
+  // Strip optional prerelease/build suffix ("-foo", "+sha"). We treat
+  // "0.7.1-staging.1" as equal-to-release "0.7.1" for gating purposes.
+  // The platform-side check uses packaging.version.Version, which sorts
+  // prereleases BEFORE the corresponding release; matching that exactly
+  // would require a fuller parser — for runtime-side defense-in-depth
+  // this conservative read is sufficient (matches release of the same
+  // base triple).
+  const base = version.split(/[-+]/)[0] ?? version;
+  const parts = base.split(".");
+  if (parts.length !== 3) return null;
+  // Reject components with anything other than ASCII digits to avoid
+  // Number.parseInt's lenient prefix-parse — e.g. "0.8.0foo" would
+  // otherwise coerce to [0, 8, 0] and silently pass the gate, defeating
+  // the parse-failure-fail-open contract in evaluateRuntimeCompatibility.
+  // Leading zeros (e.g. "01.02.03") are intentionally accepted since
+  // they round-trip to the same numeric triple as the un-padded form.
+  if (!parts.every((p) => /^\d+$/.test(p))) return null;
+  const [maj, min, pat] = parts.map((p) => Number(p));
+  if (![maj, min, pat].every((n) => Number.isFinite(n) && n >= 0)) {
+    return null;
+  }
+  return [maj!, min!, pat!] as const;
+}
+
+// -1 if a < b, 0 if equal, +1 if a > b. Returns null on parse failure.
+export function compareSemver(a: string, b: string): -1 | 0 | 1 | null {
+  const ta = parseSemverTriple(a);
+  const tb = parseSemverTriple(b);
+  if (!ta || !tb) return null;
+  for (let i = 0; i < 3; i++) {
+    if (ta[i]! < tb[i]!) return -1;
+    if (ta[i]! > tb[i]!) return +1;
+  }
+  return 0;
+}
+
+export interface RuntimeCompatibility {
+  min_runtime_version: string;
+  max_runtime_version: string | null;
+}
+
+export type RuntimeCompatibilityResult =
+  | { ok: true }
+  | {
+      ok: false;
+      reason: "version_incompatible";
+      bundle_compat: RuntimeCompatibility;
+      runtime_version: string;
+    };
+
+export function formatRuntimeCompatibilityMessage(
+  compat: RuntimeCompatibility,
+  runtimeVersion: string,
+): string {
+  const range = compat.max_runtime_version
+    ? `${compat.min_runtime_version}–${compat.max_runtime_version}`
+    : `${compat.min_runtime_version}+`;
+  return `Cannot import: bundle requires runtime ${range}, but this runtime is ${runtimeVersion}. Update your runtime before importing.`;
+}
+
+export function evaluateRuntimeCompatibility(
+  compat: RuntimeCompatibility,
+  runtimeVersion: string,
+): RuntimeCompatibilityResult {
+  if (compat.min_runtime_version === LEGACY_RUNTIME_VERSION_SENTINEL) {
+    return { ok: true };
+  }
+  const minCmp = compareSemver(runtimeVersion, compat.min_runtime_version);
+  if (minCmp === null) return { ok: true };
+  if (minCmp < 0) {
+    return {
+      ok: false,
+      reason: "version_incompatible",
+      bundle_compat: compat,
+      runtime_version: runtimeVersion,
+    };
+  }
+  if (compat.max_runtime_version !== null) {
+    const maxCmp = compareSemver(runtimeVersion, compat.max_runtime_version);
+    if (maxCmp === null) return { ok: true };
+    if (maxCmp > 0) {
+      return {
+        ok: false,
+        reason: "version_incompatible",
+        bundle_compat: compat,
+        runtime_version: runtimeVersion,
+      };
+    }
+  }
+  return { ok: true };
+}

package/src/runtime/migrations/vbundle-importer.ts

@@ -16,72 +16,30 @@ import { createHash } from "node:crypto";
 import {
   copyFileSync,
   existsSync,
+  lstatSync,
   mkdirSync,
   readdirSync,
   readFileSync,
+  readlinkSync,
   rmSync,
+  symlinkSync,
   writeFileSync,
 } from "node:fs";
-import { dirname, join } from "node:path";
+import { dirname, join, resolve, sep } from "node:path";
 
 import { sanitizeConfigForTransfer } from "../../config/sanitize-for-transfer.js";
 import { isGuardianPersonaCustomized } from "../../prompts/persona-resolver.js";
 import { getLogger } from "../../util/logger.js";
+import { APP_VERSION } from "../../version.js";
 import type { PathResolver } from "./vbundle-import-analyzer.js";
+import type { RuntimeCompatibility } from "./vbundle-import-policy.js";
+import * as policy from "./vbundle-import-policy.js";
 import { mergeMetadataPreservingVellum } from "./vbundle-metadata-merge.js";
 import type { ManifestType, VBundleTarEntry } from "./vbundle-validator.js";
 import { validateVBundle } from "./vbundle-validator.js";
 
 const log = getLogger("vbundle-importer");
 
-/** Archive path for the legacy guardian user persona file. */
-export const LEGACY_USER_MD_ARCHIVE_PATH = "prompts/USER.md";
-
-/**
- * Archive paths recognized as JSON config files that must be run through
- * `sanitizeConfigForTransfer` before writing to disk. Exported so the
- * streaming importer can apply the same defense-in-depth treatment.
- */
-export const CONFIG_ARCHIVE_PATHS: ReadonlySet<string> = new Set([
-  "workspace/config.json",
-  "config/settings.json",
-]);
-
-/**
- * Archive path for the credential metadata file. On import, bundle contents
- * must be merged with the target's live `vellum:*` entries so the gateway's
- * `readServiceCredentials` can still locate the platform API key after a
- * local→platform teleport. Both importers consult this constant.
- */
-const CREDENTIAL_METADATA_ARCHIVE_PATH =
-  "workspace/data/credentials/metadata.json";
-
-/**
- * Paths inside the workspace directory that must be preserved across an
- * import when the bundle does not carry entries for them.
- *
- * Each entry is a path RELATIVE to the workspace root. Two kinds of live
- * data warrant carry-over:
- *
- * - `embedding-models` / `deprecated`: large local caches / quarantine
- *   directories that are never shipped inside bundles but are expensive
- *   or impossible to reconstruct from an import.
- * - `data/db` / `data/qdrant`: user-critical state (SQLite assistant DB;
- *   Qdrant vector store). If the bundle omits them — e.g. a partial
- *   bundle covering only prompts/config — the live copies must survive.
- *
- * Both the buffer-based `commitImport` (which selectively clears the
- * workspace in place) and the streaming importer (which swaps the
- * workspace with a freshly-populated temp tree) consult this list so
- * their behavior stays in sync.
- */
-export const WORKSPACE_PRESERVE_PATHS: readonly string[] = [
-  "embedding-models",
-  "deprecated",
-  "data/db",
-  "data/qdrant",
-];
-
 // ---------------------------------------------------------------------------
 // Public types
 // ---------------------------------------------------------------------------
@@ -130,6 +88,12 @@ export type ImportCommitResult =
       errors: Array<{ code: string; message: string; path?: string }>;
     }
   | { ok: false; reason: "extraction_failed"; message: string }
+  | {
+      ok: false;
+      reason: "version_incompatible";
+      bundle_compat: RuntimeCompatibility;
+      runtime_version: string;
+    }
   | {
       ok: false;
       reason: "write_failed";
@@ -154,6 +118,28 @@ function generateBackupPath(diskPath: string): string {
   return `${diskPath}.backup-${timestamp}`;
 }
 
+/**
+ * Defense-in-depth: returns true if `linkTarget`, when resolved relative to
+ * the symlink's own directory (`dirname(diskPath)`), lands outside the
+ * supplied `workspaceDir`. The validator (`validateVBundle`) already enforces
+ * archive-relative containment, but we re-check here so the buffer importer
+ * is safe even if a caller passes a hand-built `preValidatedManifest`.
+ *
+ * Returns false when `workspaceDir` is undefined — the importer is permitted
+ * to write outside any workspace in that mode (e.g. legacy hooks-only
+ * imports).
+ */
+function isOutsideWorkspace(
+  diskPath: string,
+  linkTarget: string,
+  workspaceDir: string | undefined,
+): boolean {
+  if (!workspaceDir) return false;
+  const resolved = resolve(dirname(diskPath), linkTarget);
+  const ws = resolve(workspaceDir);
+  return resolved !== ws && !resolved.startsWith(ws + sep);
+}
+
 // ---------------------------------------------------------------------------
 // Core importer
 // ---------------------------------------------------------------------------
@@ -217,19 +203,29 @@ export function commitImport(options: ImportCommitOptions): ImportCommitResult {
     entryMap = validation.entries;
   }
 
+  // Defense-in-depth: refuse to import a bundle whose declared compat range
+  // excludes this runtime BEFORE any state mutation. The platform-side gate
+  // is the primary check; this catches legacy bundles whose ExportJob row
+  // predates PR #5470 (compat columns NULL → platform gate skipped) and
+  // any caller that bypasses the platform-issued signed URL flow.
+  const compatResult = policy.evaluateRuntimeCompatibility(
+    manifest.compatibility,
+    APP_VERSION,
+  );
+  if (!compatResult.ok) {
+    return {
+      ok: false,
+      reason: "version_incompatible",
+      bundle_compat: compatResult.bundle_compat,
+      runtime_version: compatResult.runtime_version,
+    };
+  }
+
   // Directories to preserve when clearing the workspace. Derived from the
   // shared WORKSPACE_PRESERVE_PATHS list so the streaming importer's
   // carry-over logic and this in-place clear stay in sync.
-  const WORKSPACE_SKIP_DIRS = new Set<string>();
-  const DATA_SKIP_DIRS = new Set<string>();
-  for (const rel of WORKSPACE_PRESERVE_PATHS) {
-    const parts = rel.split("/");
-    if (parts.length === 1) {
-      WORKSPACE_SKIP_DIRS.add(parts[0]);
-    } else if (parts.length === 2 && parts[0] === "data") {
-      DATA_SKIP_DIRS.add(parts[1]);
-    }
-  }
+  const { topLevelSkipDirs, dataSubdirSkipDirs } =
+    policy.partitionWorkspacePreserveSkipDirs();
 
   // Step 1b: Clear the workspace directory before restore if the bundle
   // contains new-format workspace/ entries. This ensures an exact-match
@@ -247,7 +243,9 @@ export function commitImport(options: ImportCommitOptions): ImportCommitResult {
   // "workspace/../../etc/passwd") from triggering a workspace purge while
   // resolving to nothing.
   const hasWorkspaceEntries = manifest.contents.some(
-    (f) => f.path.startsWith("workspace/") && !!pathResolver.resolve(f.path),
+    (f) =>
+      policy.isWorkspaceNamespacedArchivePath(f.path) &&
+      !!pathResolver.resolve(f.path),
   );
 
   // Capture the target's credential metadata BEFORE the workspace clear
@@ -257,7 +255,7 @@ export function commitImport(options: ImportCommitOptions): ImportCommitResult {
   // (`vellum:*`) entries across the overwrite.
   let liveCredentialMetadataJson: string | null = null;
   const credentialMetadataDiskPath = pathResolver.resolve(
-    CREDENTIAL_METADATA_ARCHIVE_PATH,
+    policy.CREDENTIAL_METADATA_ARCHIVE_PATH,
   );
   if (credentialMetadataDiskPath && existsSync(credentialMetadataDiskPath)) {
     try {
@@ -279,7 +277,7 @@ export function commitImport(options: ImportCommitOptions): ImportCommitResult {
       // Clear workspace contents selectively, preserving skip dirs
       const topEntries = readdirSync(workspaceDir, { withFileTypes: true });
       for (const entry of topEntries) {
-        if (WORKSPACE_SKIP_DIRS.has(entry.name)) continue;
+        if (topLevelSkipDirs.has(entry.name)) continue;
 
         const entryPath = join(workspaceDir, entry.name);
         if (entry.name === "data" && entry.isDirectory()) {
@@ -287,7 +285,7 @@ export function commitImport(options: ImportCommitOptions): ImportCommitResult {
           // (critical user data) but clear everything else
           const dataEntries = readdirSync(entryPath, { withFileTypes: true });
           for (const dataEntry of dataEntries) {
-            if (DATA_SKIP_DIRS.has(dataEntry.name)) continue;
+            if (dataSubdirSkipDirs.has(dataEntry.name)) continue;
             rmSync(join(entryPath, dataEntry.name), {
               recursive: true,
               force: true,
@@ -339,6 +337,185 @@ export function commitImport(options: ImportCommitOptions): ImportCommitResult {
       continue;
     }
 
+    // Symlink branch: recreate the entry on disk as a real symlink so the
+    // post-import workspace mirrors the source's link topology rather than
+    // duplicating bytes. The validator already enforces archive-relative
+    // containment, sha256-over-target, and size==0 — we still reapply
+    // absolute-target and workspace-escape gates here so a hand-built
+    // `preValidatedManifest` cannot bypass them.
+    if (fileEntry.link_target !== undefined) {
+      const archiveEntry = entryMap.get(fileEntry.path);
+      if (!archiveEntry) {
+        importedFiles.push({
+          path: fileEntry.path,
+          disk_path: diskPath,
+          action: "skipped",
+          size: 0,
+          sha256: fileEntry.sha256,
+          backup_path: null,
+        });
+        warnings.push(
+          `Skipped "${fileEntry.path}": declared in manifest but not found in archive`,
+        );
+        continue;
+      }
+
+      // Legacy guardian persona (prompts/USER.md) is translated to the
+      // current guardian's users/<slug>.md by DefaultPathResolver. If the
+      // bundle ships USER.md as a symlink and the target already holds
+      // user-authored content, skip rather than clobber — mirrors the
+      // protection in the regular-file branch below.
+      if (
+        policy.isLegacyPersonaArchivePath(fileEntry.path) &&
+        isGuardianPersonaCustomized(diskPath)
+      ) {
+        log.warn(
+          { archivePath: fileEntry.path, diskPath },
+          "Skipping legacy prompts/USER.md symlink import: guardian persona is already customized",
+        );
+        warnings.push(
+          `Skipped "${fileEntry.path}": guardian persona at "${diskPath}" is already customized`,
+        );
+        importedFiles.push({
+          path: fileEntry.path,
+          disk_path: diskPath,
+          action: "skipped",
+          size: 0,
+          sha256: fileEntry.sha256,
+          backup_path: null,
+        });
+        continue;
+      }
+
+      // Defense-in-depth path-traversal gate.
+      if (
+        fileEntry.link_target.startsWith("/") ||
+        isOutsideWorkspace(diskPath, fileEntry.link_target, workspaceDir)
+      ) {
+        importedFiles.push({
+          path: fileEntry.path,
+          disk_path: diskPath,
+          action: "skipped",
+          size: 0,
+          sha256: fileEntry.sha256,
+          backup_path: null,
+        });
+        warnings.push(
+          `Skipped "${fileEntry.path}": symlink target "${fileEntry.link_target}" escapes workspace`,
+        );
+        continue;
+      }
+
+      // Back up an existing entry at diskPath, if any. Use `lstatSync` so we
+      // detect a pre-existing dangling symlink (which `existsSync` reports
+      // as missing) — `symlinkSync` would otherwise fail with EEXIST. For
+      // regular files and resolvable symlinks we copy the file contents into
+      // the backup, matching the existing contract; for dangling symlinks
+      // we preserve the linkname via `readlinkSync`+`symlinkSync` so the
+      // original entry can be inspected after the import. The pre-existing
+      // entry is removed before `symlinkSync` so the new symlink can land.
+      let backupPath: string | null = null;
+      let action: ImportFileAction;
+      let preExistingEntry = false;
+      let preExistingIsSymlink = false;
+      try {
+        const stats = lstatSync(diskPath);
+        preExistingEntry = true;
+        preExistingIsSymlink = stats.isSymbolicLink();
+      } catch {
+        // ENOENT — no pre-existing entry at this path.
+      }
+      if (preExistingEntry) {
+        backupPath = generateBackupPath(diskPath);
+        try {
+          if (preExistingIsSymlink) {
+            const oldTarget = readlinkSync(diskPath);
+            symlinkSync(oldTarget, backupPath);
+          } else {
+            copyFileSync(diskPath, backupPath);
+          }
+          backupsCreated++;
+        } catch (err) {
+          return {
+            ok: false,
+            reason: "write_failed",
+            message: `Failed to back up "${diskPath}": ${
+              err instanceof Error ? err.message : String(err)
+            }`,
+            partial_report: buildPartialReport(
+              importedFiles,
+              manifest,
+              warnings,
+              backupsCreated,
+            ),
+          };
+        }
+        action = "overwritten";
+        try {
+          rmSync(diskPath, { force: true });
+        } catch {
+          /* best effort — symlinkSync below will surface the real error */
+        }
+      } else {
+        action = "created";
+      }
+
+      // Ensure parent directory exists.
+      const parentDir = dirname(diskPath);
+      if (!existsSync(parentDir)) {
+        try {
+          mkdirSync(parentDir, { recursive: true });
+        } catch (err) {
+          return {
+            ok: false,
+            reason: "write_failed",
+            message: `Failed to create directory "${parentDir}": ${
+              err instanceof Error ? err.message : String(err)
+            }`,
+            partial_report: buildPartialReport(
+              importedFiles,
+              manifest,
+              warnings,
+              backupsCreated,
+            ),
+          };
+        }
+      }
+
+      // Create the symlink. The target is stored verbatim — OS symlink
+      // semantics resolve it relative to the symlink's own directory at
+      // use time.
+      try {
+        symlinkSync(fileEntry.link_target, diskPath);
+      } catch (err) {
+        return {
+          ok: false,
+          reason: "write_failed",
+          message: `Failed to create symlink "${diskPath}" -> "${fileEntry.link_target}": ${
+            err instanceof Error ? err.message : String(err)
+          }`,
+          partial_report: buildPartialReport(
+            importedFiles,
+            manifest,
+            warnings,
+            backupsCreated,
+          ),
+        };
+      }
+
+      importedFiles.push({
+        path: fileEntry.path,
+        disk_path: diskPath,
+        action,
+        size: 0,
+        sha256: fileEntry.sha256,
+        backup_path: backupPath,
+      });
+      // Skip the regular-file branches (and the post-write integrity check,
+      // which would dereference the symlink and read the target's bytes).
+      continue;
+    }
+
     const archiveEntry = entryMap.get(fileEntry.path);
     if (!archiveEntry) {
       // File declared in manifest but not found in archive — should not
@@ -363,7 +540,7 @@ export function commitImport(options: ImportCommitOptions): ImportCommitResult {
     // than clobber — the user has curated their persona since the
     // bundle was exported.
     if (
-      fileEntry.path === LEGACY_USER_MD_ARCHIVE_PATH &&
+      policy.isLegacyPersonaArchivePath(fileEntry.path) &&
       isGuardianPersonaCustomized(diskPath)
     ) {
       log.warn(
@@ -438,7 +615,7 @@ export function commitImport(options: ImportCommitOptions): ImportCommitResult {
 
     // Sanitize config files to strip environment-specific fields (defense-in-depth)
     let dataToWrite: Uint8Array = archiveEntry.data;
-    if (CONFIG_ARCHIVE_PATHS.has(fileEntry.path)) {
+    if (policy.isConfigArchivePath(fileEntry.path)) {
       const configJson = new TextDecoder().decode(archiveEntry.data);
       const sanitized = sanitizeConfigForTransfer(configJson);
       dataToWrite = new TextEncoder().encode(sanitized);
@@ -450,7 +627,7 @@ export function commitImport(options: ImportCommitOptions): ImportCommitResult {
     // would wipe them and break the gateway's vellum credential read.
     // We use the snapshot captured BEFORE the workspace clear because
     // Step 1b may have already removed the live file.
-    if (fileEntry.path === CREDENTIAL_METADATA_ARCHIVE_PATH) {
+    if (policy.isCredentialMetadataArchivePath(fileEntry.path)) {
       const bundleJson = new TextDecoder().decode(archiveEntry.data);
       const merged = mergeMetadataPreservingVellum(
         bundleJson,
@@ -536,8 +713,8 @@ export function commitImport(options: ImportCommitOptions): ImportCommitResult {
   // run (e.g. workspaceDir unset) the live metadata.json is still on
   // disk untouched — we must not rewrite it here or we would drop the
   // non-vellum entries the caller chose to keep.
-  const bundleHadMetadata = manifest.contents.some(
-    (f) => f.path === CREDENTIAL_METADATA_ARCHIVE_PATH,
+  const bundleHadMetadata = manifest.contents.some((f) =>
+    policy.isCredentialMetadataArchivePath(f.path),
   );
   if (
     workspaceWasCleared &&