@vellumai/assistant 0.7.0 → 0.7.2

package/src/backup/__tests__/paths.test.ts

@@ -5,7 +5,6 @@ import { afterEach, describe, expect, test } from "bun:test";
 import {
   deriveSafeAncestor,
   formatBackupFilename,
-  getBackupKeyPath,
   getBackupRootDir,
   getDefaultOffsiteBackupsDir,
   getICloudDriveRoot,
@@ -162,27 +161,6 @@ describe("resolveOffsiteDestinations", () => {
   });
 });
 
-describe("getBackupKeyPath", () => {
-  const ORIGINAL_KEY_PATH = process.env.VELLUM_BACKUP_KEY_PATH;
-
-  afterEach(() => {
-    if (ORIGINAL_KEY_PATH === undefined) {
-      delete process.env.VELLUM_BACKUP_KEY_PATH;
-    } else {
-      process.env.VELLUM_BACKUP_KEY_PATH = ORIGINAL_KEY_PATH;
-    }
-  });
-
-  test("ends with /protected/backup.key when env var is unset", () => {
-    delete process.env.VELLUM_BACKUP_KEY_PATH;
-    expect(getBackupKeyPath().endsWith("/protected/backup.key")).toBe(true);
-  });
-
-  test("returns the env var override when VELLUM_BACKUP_KEY_PATH is set", () => {
-    process.env.VELLUM_BACKUP_KEY_PATH = "/workspace/.backup.key";
-    expect(getBackupKeyPath()).toBe("/workspace/.backup.key");
-  });
-});
 
 describe("formatBackupFilename", () => {
   const fixture = new Date("2026-04-11T15:30:45.000Z");

package/src/backup/__tests__/restore.test.ts

@@ -22,15 +22,14 @@ import { randomBytes } from "node:crypto";
 import {
   existsSync,
   mkdirSync,
-  readdirSync,
   rmSync,
   writeFileSync,
 } from "node:fs";
-import { open } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 
+import { defaultV1Options } from "../../runtime/migrations/__tests__/v1-test-helpers.js";
 import { buildVBundle } from "../../runtime/migrations/vbundle-builder.js";
 import type { PathResolver } from "../../runtime/migrations/vbundle-import-analyzer.js";
 import type {
@@ -39,7 +38,6 @@ import type {
 } from "../../runtime/migrations/vbundle-importer.js";
 import type { ManifestType } from "../../runtime/migrations/vbundle-validator.js";
 import { restoreFromSnapshot, verifySnapshot } from "../restore.js";
-import { ENCRYPTED_HEADER_SIZE, encryptFile } from "../stream-crypt.js";
 
 // ---------------------------------------------------------------------------
 // Fixtures
@@ -78,11 +76,13 @@ const NULL_RESOLVER: PathResolver = {
  * the file path along with the manifest the builder embedded so tests can
  * compare against it.
  */
-function writeTinyPlaintextBundle(
-  fileName: string,
-): { path: string; manifest: ManifestType } {
+function writeTinyPlaintextBundle(fileName: string): {
+  path: string;
+  manifest: ManifestType;
+} {
   const { archive, manifest } = buildVBundle({
     files: [
+      { path: "data/db/assistant.db", data: new Uint8Array() },
       {
         path: "workspace/notes/hello.txt",
         data: new TextEncoder().encode("hello world"),
@@ -92,8 +92,7 @@ function writeTinyPlaintextBundle(
         data: new TextEncoder().encode("a tiny bundle for tests"),
       },
     ],
-    source: "restore-test",
-    description: "tiny bundle for restore.test.ts",
+    ...defaultV1Options(),
   });
 
   const path = join(TEST_DIR, fileName);
@@ -117,21 +116,35 @@ function makeStubCommitImpl(): {
   const calls: RecordedCall[] = [];
   const commitImpl = (options: ImportCommitOptions): ImportCommitResult => {
     calls.push({ options });
-    const manifest =
+    const manifest: ManifestType =
       options.preValidatedManifest ??
       ({
-        schema_version: "1.0",
+        schema_version: 1,
+        bundle_id: "00000000-0000-4000-8000-000000000000",
         created_at: new Date().toISOString(),
-        files: [],
-        manifest_sha256: "stub",
-      } satisfies ManifestType);
+        assistant: { id: "self", name: "Test", runtime_version: "0.0.0-test" },
+        origin: { mode: "self-hosted-local" },
+        compatibility: {
+          min_runtime_version: "0.0.0-test",
+          max_runtime_version: null,
+        },
+        contents: [],
+        checksum:
+          "0000000000000000000000000000000000000000000000000000000000000000",
+        secrets_redacted: false,
+        export_options: {
+          include_logs: false,
+          include_browser_state: false,
+          include_memory_vectors: false,
+        },
+      } as ManifestType);
     return {
       ok: true,
       report: {
         success: true,
         summary: {
-          total_files: manifest.files.length,
-          files_created: manifest.files.length,
+          total_files: manifest.contents.length,
+          files_created: manifest.contents.length,
           files_overwritten: 0,
           files_skipped: 0,
           backups_created: 0,
@@ -145,26 +158,6 @@ function makeStubCommitImpl(): {
   return { commitImpl, calls };
 }
 
-/** Throwing stub used to verify temp-file cleanup on commit failure. */
-function makeThrowingCommitImpl(): (
-  options: ImportCommitOptions,
-) => ImportCommitResult {
-  return () => {
-    throw new Error("simulated commit failure");
-  };
-}
-
-/**
- * Snapshot the OS temp directory so tests can later verify that nothing
- * matching `vellum-restore-*.vbundle` was left behind. Restricting the
- * search to that prefix avoids racing with unrelated processes.
- */
-function listRestoreTempArtifacts(): string[] {
-  return readdirSync(tmpdir()).filter((name) =>
-    name.startsWith("vellum-restore-"),
-  );
-}
-
 // ---------------------------------------------------------------------------
 // Tests
 // ---------------------------------------------------------------------------
@@ -173,87 +166,40 @@ describe("verifySnapshot", () => {
   test("plaintext: returns valid:true and the manifest for a well-formed bundle", async () => {
     const { path, manifest } = writeTinyPlaintextBundle("plain.vbundle");
 
-    const result = await verifySnapshot(path, {});
+    const result = await verifySnapshot(path);
 
     expect(result.valid).toBe(true);
     expect(result.manifest).toBeDefined();
     expect(result.error).toBeUndefined();
-    expect(result.manifest?.manifest_sha256).toBe(manifest.manifest_sha256);
-    expect(result.manifest?.files.length).toBe(2);
-  });
-
-  test("encrypted: returns valid:true after decrypting first", async () => {
-    const { path: plainPath } = writeTinyPlaintextBundle("plain.vbundle");
-    const encPath = join(TEST_DIR, "plain.vbundle.enc");
-    const key = randomBytes(32);
-    await encryptFile(plainPath, encPath, key);
-
-    const before = listRestoreTempArtifacts();
-    const result = await verifySnapshot(encPath, { key });
-    const after = listRestoreTempArtifacts();
-
-    expect(result.valid).toBe(true);
-    expect(result.manifest).toBeDefined();
-    // The decrypted temp file must be cleaned up after verification.
-    expect(after.length).toBe(before.length);
+    expect(result.manifest?.checksum).toBe(manifest.checksum);
+    // 3 = synthetic data/db/assistant.db + workspace/notes/hello.txt + workspace/notes/about.txt
+    expect(result.manifest?.contents.length).toBe(3);
   });
 
-  test("encrypted with no key throws the typed error", async () => {
-    const { path: plainPath } = writeTinyPlaintextBundle("plain.vbundle");
+  test("encrypted path is rejected with a gateway redirect error", async () => {
+    // Write a dummy file with .vbundle.enc extension — the content doesn't
+    // matter because the rejection is based purely on file extension.
     const encPath = join(TEST_DIR, "plain.vbundle.enc");
-    const key = randomBytes(32);
-    await encryptFile(plainPath, encPath, key);
-
-    await expect(verifySnapshot(encPath, {})).rejects.toThrow(
-      "Encrypted snapshot requires a decryption key",
-    );
-  });
-
-  test("corrupt ciphertext: returns valid:false with the decrypt error", async () => {
-    const { path: plainPath } = writeTinyPlaintextBundle("plain.vbundle");
-    const encPath = join(TEST_DIR, "plain.vbundle.enc");
-    const key = randomBytes(32);
-    await encryptFile(plainPath, encPath, key);
-
-    // Flip a byte inside the ciphertext body — auth tag verification fails.
-    const flipOffset = ENCRYPTED_HEADER_SIZE + 4;
-    const fh = await open(encPath, "r+");
-    try {
-      const one = Buffer.alloc(1);
-      await fh.read(one, 0, 1, flipOffset);
-      one[0] = one[0] ^ 0xff;
-      await fh.write(one, 0, 1, flipOffset);
-    } finally {
-      await fh.close();
-    }
-
-    const before = listRestoreTempArtifacts();
-    const result = await verifySnapshot(encPath, { key });
-    const after = listRestoreTempArtifacts();
+    writeFileSync(encPath, "dummy encrypted content");
 
+    const result = await verifySnapshot(encPath);
     expect(result.valid).toBe(false);
-    expect(result.error).toBeDefined();
-    expect(result.manifest).toBeUndefined();
-    // Even on failure, the decrypted temp file must be cleaned up.
-    expect(after.length).toBe(before.length);
+    expect(result.error).toMatch(/gateway/i);
   });
 
   test("corrupt manifest: returns valid:false with the validation error", async () => {
-    // Build a valid bundle, then re-encrypt with the manifest tampered.
-    // We tamper at the plaintext bundle level so encryption succeeds but
-    // validateVBundle catches the bad manifest.
+    // Build a valid bundle, then tamper bytes in the middle
     const { archive } = buildVBundle({
       files: [
+        { path: "data/db/assistant.db", data: new Uint8Array() },
         {
           path: "workspace/notes/hello.txt",
           data: new TextEncoder().encode("hello"),
         },
       ],
+      ...defaultV1Options(),
     });
 
-    // Flip a few bytes in the middle of the gzipped archive — this almost
-    // always corrupts the gzip stream itself or the embedded manifest JSON,
-    // both of which are validation failures (NOT decryption failures).
     const tampered = Buffer.from(archive);
     const tamperOffset = Math.floor(tampered.length / 2);
     tampered[tamperOffset] = tampered[tamperOffset] ^ 0xff;
@@ -262,7 +208,7 @@ describe("verifySnapshot", () => {
     const path = join(TEST_DIR, "corrupt.vbundle");
     writeFileSync(path, tampered);
 
-    const result = await verifySnapshot(path, {});
+    const result = await verifySnapshot(path);
 
     expect(result.valid).toBe(false);
     expect(result.error).toBeDefined();
@@ -290,55 +236,22 @@ describe("restoreFromSnapshot", () => {
 
     expect(calls.length).toBe(1);
     const passed = calls[0].options;
-    // The wrapper should pass the pre-validated manifest + entries so
-    // commitImport doesn't re-validate.
-    expect(passed.preValidatedManifest?.manifest_sha256).toBe(
-      manifest.manifest_sha256,
-    );
+    expect(passed.preValidatedManifest?.checksum).toBe(manifest.checksum);
     expect(passed.preValidatedEntries).toBeDefined();
     expect(passed.preValidatedEntries?.has("manifest.json")).toBe(true);
-    expect(
-      passed.preValidatedEntries?.has("workspace/notes/hello.txt"),
-    ).toBe(true);
-    // archiveData must be the actual bundle bytes.
+    expect(passed.preValidatedEntries?.has("workspace/notes/hello.txt")).toBe(
+      true,
+    );
     expect(passed.archiveData).toBeInstanceOf(Uint8Array);
     expect(passed.archiveData.length).toBeGreaterThan(0);
 
-    // Public result is shaped correctly.
-    expect(result.manifest.manifest_sha256).toBe(manifest.manifest_sha256);
-    expect(result.restoredFiles).toBe(2);
+    expect(result.manifest.checksum).toBe(manifest.checksum);
+    expect(result.restoredFiles).toBe(3);
   });
 
-  test("encrypted round-trip: decrypts then commits, and cleans up the temp file", async () => {
-    const { path: plainPath, manifest } =
-      writeTinyPlaintextBundle("plain.vbundle");
+  test("encrypted path is rejected with a gateway redirect error", async () => {
     const encPath = join(TEST_DIR, "plain.vbundle.enc");
-    const key = randomBytes(32);
-    await encryptFile(plainPath, encPath, key);
-
-    const { commitImpl, calls } = makeStubCommitImpl();
-
-    const before = listRestoreTempArtifacts();
-    const result = await restoreFromSnapshot(encPath, {
-      key,
-      pathResolver: NULL_RESOLVER,
-      commitImpl,
-    });
-    const after = listRestoreTempArtifacts();
-
-    expect(calls.length).toBe(1);
-    expect(result.manifest.manifest_sha256).toBe(manifest.manifest_sha256);
-    expect(result.restoredFiles).toBe(2);
-
-    // Decrypted temp file must be cleaned up after the call.
-    expect(after.length).toBe(before.length);
-  });
-
-  test("encrypted with no key throws the typed error", async () => {
-    const { path: plainPath } = writeTinyPlaintextBundle("plain.vbundle");
-    const encPath = join(TEST_DIR, "plain.vbundle.enc");
-    const key = randomBytes(32);
-    await encryptFile(plainPath, encPath, key);
+    writeFileSync(encPath, "dummy encrypted content");
 
     const { commitImpl, calls } = makeStubCommitImpl();
 
@@ -347,36 +260,15 @@ describe("restoreFromSnapshot", () => {
         pathResolver: NULL_RESOLVER,
         commitImpl,
       }),
-    ).rejects.toThrow("Encrypted snapshot requires a decryption key");
+    ).rejects.toThrow(/gateway/i);
 
     expect(calls.length).toBe(0);
   });
 
-  test("temp decrypted file is cleaned up after a commit failure", async () => {
-    const { path: plainPath } = writeTinyPlaintextBundle("plain.vbundle");
-    const encPath = join(TEST_DIR, "plain.vbundle.enc");
-    const key = randomBytes(32);
-    await encryptFile(plainPath, encPath, key);
-
-    const before = listRestoreTempArtifacts();
-    await expect(
-      restoreFromSnapshot(encPath, {
-        key,
-        pathResolver: NULL_RESOLVER,
-        commitImpl: makeThrowingCommitImpl(),
-      }),
-    ).rejects.toThrow("simulated commit failure");
-    const after = listRestoreTempArtifacts();
-
-    expect(after.length).toBe(before.length);
-  });
-
   test("credentials in a bundle are ignored and not surfaced to the caller", async () => {
-    // Older bundles (or a shared vbundle format) may include `credentials/*`
-    // entries. Backup restore explicitly drops them — credentials live in
-    // the OS keychain / CES and are not part of the backup round trip.
     const { archive, manifest } = buildVBundle({
       files: [
+        { path: "data/db/assistant.db", data: new Uint8Array() },
         {
           path: "workspace/notes/hello.txt",
           data: new TextEncoder().encode("hello"),
@@ -386,6 +278,7 @@ describe("restoreFromSnapshot", () => {
           data: new TextEncoder().encode("sk-test-1234"),
         },
       ],
+      ...defaultV1Options(),
     });
 
     const path = join(TEST_DIR, "with-creds.vbundle");
@@ -397,14 +290,11 @@ describe("restoreFromSnapshot", () => {
       commitImpl,
     });
 
-    // The restore result must not expose a `credentials` field — the public
-    // type only has `manifest` and `restoredFiles`.
-    expect(result.manifest.manifest_sha256).toBe(manifest.manifest_sha256);
+    expect(result.manifest.checksum).toBe(manifest.checksum);
     expect("credentials" in result).toBe(false);
   });
 
   test("validation failure: throws with the validation error message", async () => {
-    // Write garbage to a .vbundle path — gzip decompression will fail.
     const path = join(TEST_DIR, "garbage.vbundle");
     writeFileSync(path, Buffer.from("not a real bundle"));
 
@@ -417,14 +307,10 @@ describe("restoreFromSnapshot", () => {
       }),
     ).rejects.toThrow(/Snapshot failed validation/);
 
-    // commitImpl must NOT have been called when validation fails.
     expect(calls.length).toBe(0);
   });
 
   test("resetDbImpl runs before commitImpl and is skipped when validation fails", async () => {
-    // Happy path: resetDb must be called, and must be called BEFORE the
-    // commit step so the SQLite handle is released before assistant.db is
-    // overwritten on disk.
     const { path } = writeTinyPlaintextBundle("plain.vbundle");
     const order: string[] = [];
     const { commitImpl } = makeStubCommitImpl();
@@ -443,9 +329,6 @@ describe("restoreFromSnapshot", () => {
 
     expect(order).toEqual(["reset", "commit"]);
 
-    // Failure path: when validation fails, resetDb must NOT be invoked —
-    // there's no reason to close the DB singleton if we're not going to
-    // overwrite anything on disk.
     const garbagePath = join(TEST_DIR, "garbage-for-reset.vbundle");
     writeFileSync(garbagePath, Buffer.from("not a real bundle"));
     let resetCallsOnInvalid = 0;
@@ -466,11 +349,7 @@ describe("restoreFromSnapshot", () => {
   test("commit returning a write_failed result is surfaced as an error", async () => {
     const { path } = writeTinyPlaintextBundle("plain.vbundle");
 
-    // Stub that simulates a write failure (the importer returns this for
-    // disk errors like permission denied or partial bundle writes).
-    const failingCommit = (
-      _opts: ImportCommitOptions,
-    ): ImportCommitResult => ({
+    const failingCommit = (_opts: ImportCommitOptions): ImportCommitResult => ({
       ok: false,
       reason: "write_failed",
       message: "disk full",
@@ -483,6 +362,44 @@ describe("restoreFromSnapshot", () => {
       }),
     ).rejects.toThrow(/disk full/);
   });
+
+  test("version-incompatible bundle short-circuits before resetDbImpl and commitImpl", async () => {
+    // Bundle declares it requires runtime 99.0.0+, but the test process is
+    // far below that. The restore wrapper must pre-check compat before the
+    // DB close/reopen cycle and skip both resetDbImpl and commitImpl.
+    const incompatPath = join(TEST_DIR, "incompat.vbundle");
+    const { archive } = buildVBundle({
+      files: [
+        { path: "data/db/assistant.db", data: new Uint8Array() },
+        {
+          path: "workspace/notes/hello.txt",
+          data: new TextEncoder().encode("hello"),
+        },
+      ],
+      ...defaultV1Options(),
+      compatibility: {
+        min_runtime_version: "99.0.0",
+        max_runtime_version: null,
+      },
+    });
+    writeFileSync(incompatPath, archive);
+
+    const { commitImpl, calls } = makeStubCommitImpl();
+    let resetCalls = 0;
+
+    await expect(
+      restoreFromSnapshot(incompatPath, {
+        pathResolver: NULL_RESOLVER,
+        commitImpl,
+        resetDbImpl: () => {
+          resetCalls += 1;
+        },
+      }),
+    ).rejects.toThrow(/Snapshot restore failed.*99\.0\.0/);
+
+    expect(resetCalls).toBe(0);
+    expect(calls.length).toBe(0);
+  });
 });
 
 describe("snapshot path detection", () => {
@@ -490,7 +407,7 @@ describe("snapshot path detection", () => {
     const path = join(TEST_DIR, "missing.vbundle");
     expect(existsSync(path)).toBe(false);
 
-    const result = await verifySnapshot(path, {});
+    const result = await verifySnapshot(path);
 
     expect(result.valid).toBe(false);
     expect(result.error).toBeDefined();

package/src/backup/paths.ts

@@ -1,12 +1,9 @@
 import { homedir, userInfo } from "node:os";
 import { dirname, isAbsolute, join } from "node:path";
 
-import {
-  getBackupDirOverride,
-  getBackupKeyPathOverride,
-} from "../config/env-registry.js";
+import { getBackupDirOverride } from "../config/env-registry.js";
 import type { BackupDestination } from "../config/schema.js";
-import { getProtectedDir } from "../util/platform.js";
+
 
 /**
  * Returns the backup root directory. Respects the `VELLUM_BACKUP_DIR`
@@ -133,16 +130,6 @@ export function resolveOffsiteDestinations(
   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