@vellumai/assistant 0.7.0 → 0.7.2

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
@@ -246,8 +242,10 @@ export function commitImport(options: ImportCommitOptions): ImportCommitResult {
   // valid disk path. This prevents path-traversal entries (e.g.
   // "workspace/../../etc/passwd") from triggering a workspace purge while
   // resolving to nothing.
-  const hasWorkspaceEntries = manifest.files.some(
-    (f) => f.path.startsWith("workspace/") && !!pathResolver.resolve(f.path),
+  const hasWorkspaceEntries = manifest.contents.some(
+    (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,
@@ -314,7 +312,7 @@ export function commitImport(options: ImportCommitOptions): ImportCommitResult {
   const warnings: string[] = [];
   let backupsCreated = 0;
 
-  for (const fileEntry of manifest.files) {
+  for (const fileEntry of manifest.contents) {
     // Credential entries are handled separately by extractCredentialsFromBundle()
     // in migration-routes.ts — skip them silently without warnings or skip counts.
     if (fileEntry.path.startsWith("credentials/")) {
@@ -329,7 +327,7 @@ export function commitImport(options: ImportCommitOptions): ImportCommitResult {
         path: fileEntry.path,
         disk_path: "",
         action: "skipped",
-        size: fileEntry.size,
+        size: fileEntry.size_bytes,
         sha256: fileEntry.sha256,
         backup_path: null,
       });
@@ -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
@@ -347,7 +524,7 @@ export function commitImport(options: ImportCommitOptions): ImportCommitResult {
         path: fileEntry.path,
         disk_path: diskPath,
         action: "skipped",
-        size: fileEntry.size,
+        size: fileEntry.size_bytes,
         sha256: fileEntry.sha256,
         backup_path: null,
       });
@@ -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(
@@ -377,7 +554,7 @@ export function commitImport(options: ImportCommitOptions): ImportCommitResult {
         path: fileEntry.path,
         disk_path: diskPath,
         action: "skipped",
-        size: fileEntry.size,
+        size: fileEntry.size_bytes,
         sha256: fileEntry.sha256,
         backup_path: null,
       });
@@ -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.files.some(
-    (f) => f.path === CREDENTIAL_METADATA_ARCHIVE_PATH,
+  const bundleHadMetadata = manifest.contents.some((f) =>
+    policy.isCredentialMetadataArchivePath(f.path),
   );
   if (
     workspaceWasCleared &&
@@ -595,7 +772,7 @@ export function extractCredentialsFromBundle(
   entries: Map<string, VBundleTarEntry>,
   manifest: ManifestType,
 ): Array<{ account: string; value: string }> {
-  const manifestPaths = new Set(manifest.files.map((f) => f.path));
+  const manifestPaths = new Set(manifest.contents.map((f) => f.path));
   const credentials: Array<{ account: string; value: string }> = [];
   for (const [path, entry] of entries) {
     if (path.startsWith("credentials/") && manifestPaths.has(path)) {

package/src/runtime/migrations/vbundle-metadata-merge.ts

@@ -117,7 +117,7 @@ export function mergeMetadataPreservingVellum(
 }
 
 /** @internal For direct use by tests. */
-export const _internal = {
+const _internal = {
   VELLUM_SERVICE,
   parseMetadata,
   extractVellumRecords,