@cleocode/core 2026.4.11 → 2026.4.13

package/src/store/__tests__/backup-unpack.test.ts

@@ -0,0 +1,298 @@
+/**
+ * Tests for backup-unpack.ts (T350).
+ *
+ * Covers: unpack of unencrypted and encrypted bundles, all verification
+ * layers, BundleError codes (70–75), staging dir management, and manifest
+ * field correctness.
+ *
+ * Uses real node:sqlite DatabaseSync to seed minimal test databases.
+ * All filesystem interactions occur in temp directories; the real user's
+ * project root is never touched.
+ *
+ * @task T350
+ * @epic T311
+ */
+
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import os from 'node:os';
+import path from 'node:path';
+import type { DatabaseSync as _DatabaseSyncType } from 'node:sqlite';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { packBundle } from '../backup-pack.js';
+import { BundleError, cleanupStaging, unpackBundle } from '../backup-unpack.js';
+
+// ---------------------------------------------------------------------------
+// node:sqlite interop
+// ---------------------------------------------------------------------------
+
+const _require = createRequire(import.meta.url);
+type DatabaseSync = _DatabaseSyncType;
+const { DatabaseSync } = _require('node:sqlite') as {
+  DatabaseSync: new (...args: ConstructorParameters<typeof _DatabaseSyncType>) => DatabaseSync;
+};
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Seed a project root with the minimal .cleo layout required by packBundle.
+ * Creates: tasks.db, brain.db, conduit.db, config.json, project-info.json,
+ * project-context.json.
+ */
+function seedProject(projectRoot: string): void {
+  const cleoDir = path.join(projectRoot, '.cleo');
+  fs.mkdirSync(cleoDir, { recursive: true });
+  for (const name of ['tasks', 'brain', 'conduit']) {
+    const db = new DatabaseSync(path.join(cleoDir, `${name}.db`));
+    db.exec('CREATE TABLE t(x INTEGER); INSERT INTO t VALUES (1);');
+    db.close();
+  }
+  fs.writeFileSync(path.join(cleoDir, 'config.json'), '{}');
+  fs.writeFileSync(path.join(cleoDir, 'project-info.json'), '{}');
+  fs.writeFileSync(path.join(cleoDir, 'project-context.json'), '{}');
+}
+
+// ---------------------------------------------------------------------------
+// Test suite
+// ---------------------------------------------------------------------------
+
+describe('T350 backup-unpack', () => {
+  let tmpRoot: string;
+  let bundleDir: string;
+
+  beforeEach(() => {
+    tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'cleo-t350-root-'));
+    bundleDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cleo-t350-bundle-'));
+    seedProject(tmpRoot);
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpRoot, { recursive: true, force: true });
+    fs.rmSync(bundleDir, { recursive: true, force: true });
+  });
+
+  async function createBundle(opts?: { encrypt?: boolean; passphrase?: string }): Promise<string> {
+    const bundlePath = path.join(
+      bundleDir,
+      'test' + (opts?.encrypt === true ? '.enc' : '') + '.cleobundle.tar.gz',
+    );
+    await packBundle({
+      scope: 'project',
+      projectRoot: tmpRoot,
+      outputPath: bundlePath,
+      encrypt: opts?.encrypt,
+      passphrase: opts?.passphrase,
+    });
+    return bundlePath;
+  }
+
+  // -------------------------------------------------------------------------
+  // Unencrypted bundle — happy path
+  // -------------------------------------------------------------------------
+
+  it('unpacks an unencrypted bundle successfully', async () => {
+    const bundlePath = await createBundle();
+    const result = await unpackBundle({ bundlePath });
+    expect(result.verified.manifestSchema).toBe(true);
+    expect(result.verified.checksums).toBe(true);
+    expect(result.verified.sqliteIntegrity).toBe(true);
+    expect(result.manifest.backup.scope).toBe('project');
+    cleanupStaging(result.stagingDir);
+  });
+
+  it('returns verified.encryptionAuth=true for unencrypted bundle (N/A = pass)', async () => {
+    const bundlePath = await createBundle();
+    const result = await unpackBundle({ bundlePath });
+    expect(result.verified.encryptionAuth).toBe(true);
+    cleanupStaging(result.stagingDir);
+  });
+
+  // -------------------------------------------------------------------------
+  // Encrypted bundle — happy path
+  // -------------------------------------------------------------------------
+
+  it('unpacks an encrypted bundle with correct passphrase', async () => {
+    const bundlePath = await createBundle({ encrypt: true, passphrase: 'hunter2' });
+    const result = await unpackBundle({ bundlePath, passphrase: 'hunter2' });
+    expect(result.verified.encryptionAuth).toBe(true);
+    expect(result.verified.manifestSchema).toBe(true);
+    expect(result.verified.checksums).toBe(true);
+    expect(result.verified.sqliteIntegrity).toBe(true);
+    cleanupStaging(result.stagingDir);
+  });
+
+  // -------------------------------------------------------------------------
+  // Error: wrong passphrase → E_BUNDLE_DECRYPT (70)
+  // -------------------------------------------------------------------------
+
+  it('throws BundleError(70) on wrong passphrase', async () => {
+    const bundlePath = await createBundle({ encrypt: true, passphrase: 'hunter2' });
+    await expect(unpackBundle({ bundlePath, passphrase: 'wrong' })).rejects.toMatchObject({
+      code: 70,
+      codeName: 'E_BUNDLE_DECRYPT',
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Error: encrypted bundle without passphrase → E_BUNDLE_DECRYPT (70)
+  // -------------------------------------------------------------------------
+
+  it('throws BundleError(70) on encrypted bundle without passphrase', async () => {
+    const bundlePath = await createBundle({ encrypt: true, passphrase: 'hunter2' });
+    await expect(unpackBundle({ bundlePath })).rejects.toMatchObject({ code: 70 });
+  });
+
+  it('throws BundleError(70) on encrypted bundle with empty passphrase', async () => {
+    const bundlePath = await createBundle({ encrypt: true, passphrase: 'hunter2' });
+    await expect(unpackBundle({ bundlePath, passphrase: '' })).rejects.toMatchObject({ code: 70 });
+  });
+
+  // -------------------------------------------------------------------------
+  // Error: tampered bundle → BundleError (72 or tar error)
+  // -------------------------------------------------------------------------
+
+  it('throws BundleError on checksum mismatch (tampered bytes)', async () => {
+    const bundlePath = await createBundle();
+    // Tamper by flipping bits near the end of the file (in the compressed data)
+    const buf = fs.readFileSync(bundlePath);
+    // Flip bytes well inside the compressed payload (not the gzip header)
+    const tamperOffset = Math.floor(buf.length / 2);
+    buf[tamperOffset] = buf[tamperOffset]! ^ 0xff;
+    buf[tamperOffset + 1] = (buf[tamperOffset + 1] ?? 0) ^ 0xff;
+    fs.writeFileSync(bundlePath, buf);
+    // tar may catch the corruption before we read checksums — accept any BundleError
+    await expect(unpackBundle({ bundlePath })).rejects.toBeInstanceOf(BundleError);
+  });
+
+  // -------------------------------------------------------------------------
+  // Staging directory structure
+  // -------------------------------------------------------------------------
+
+  it('returns a valid staging dir containing manifest.json, databases/, json/', async () => {
+    const bundlePath = await createBundle();
+    const result = await unpackBundle({ bundlePath });
+    expect(fs.existsSync(path.join(result.stagingDir, 'manifest.json'))).toBe(true);
+    expect(fs.existsSync(path.join(result.stagingDir, 'databases'))).toBe(true);
+    expect(fs.existsSync(path.join(result.stagingDir, 'json'))).toBe(true);
+    cleanupStaging(result.stagingDir);
+  });
+
+  it('staging dir contains schemas/manifest-v1.json', async () => {
+    const bundlePath = await createBundle();
+    const result = await unpackBundle({ bundlePath });
+    expect(fs.existsSync(path.join(result.stagingDir, 'schemas', 'manifest-v1.json'))).toBe(true);
+    cleanupStaging(result.stagingDir);
+  });
+
+  // -------------------------------------------------------------------------
+  // cleanupStaging
+  // -------------------------------------------------------------------------
+
+  it('cleanupStaging removes the staging dir', async () => {
+    const bundlePath = await createBundle();
+    const result = await unpackBundle({ bundlePath });
+    cleanupStaging(result.stagingDir);
+    expect(fs.existsSync(result.stagingDir)).toBe(false);
+  });
+
+  it('cleanupStaging is idempotent — does not throw if already removed', async () => {
+    const bundlePath = await createBundle();
+    const result = await unpackBundle({ bundlePath });
+    cleanupStaging(result.stagingDir);
+    // Second call must not throw
+    expect(() => cleanupStaging(result.stagingDir)).not.toThrow();
+  });
+
+  // -------------------------------------------------------------------------
+  // Manifest field correctness
+  // -------------------------------------------------------------------------
+
+  it('parses manifest fields correctly', async () => {
+    const bundlePath = await createBundle();
+    const result = await unpackBundle({ bundlePath });
+    expect(result.manifest.manifestVersion).toBe('1.0.0');
+    expect(result.manifest.$schema).toBe('./schemas/manifest-v1.json');
+    expect(result.manifest.backup.scope).toBe('project');
+    expect(result.manifest.integrity.algorithm).toBe('sha256');
+    expect(result.manifest.databases.length).toBeGreaterThanOrEqual(3);
+    cleanupStaging(result.stagingDir);
+  });
+
+  it('manifest.backup.encrypted is false for unencrypted bundle', async () => {
+    const bundlePath = await createBundle();
+    const result = await unpackBundle({ bundlePath });
+    expect(result.manifest.backup.encrypted).toBe(false);
+    cleanupStaging(result.stagingDir);
+  });
+
+  it('manifest.backup.encrypted is true for encrypted bundle', async () => {
+    const bundlePath = await createBundle({ encrypt: true, passphrase: 'p@ss' });
+    const result = await unpackBundle({ bundlePath, passphrase: 'p@ss' });
+    expect(result.manifest.backup.encrypted).toBe(true);
+    cleanupStaging(result.stagingDir);
+  });
+
+  it('manifest.databases includes tasks, brain, conduit for project scope', async () => {
+    const bundlePath = await createBundle();
+    const result = await unpackBundle({ bundlePath });
+    const names = result.manifest.databases.map((d) => d.name);
+    expect(names).toContain('tasks');
+    expect(names).toContain('brain');
+    expect(names).toContain('conduit');
+    cleanupStaging(result.stagingDir);
+  });
+
+  // -------------------------------------------------------------------------
+  // BundleError class shape
+  // -------------------------------------------------------------------------
+
+  it('BundleError extends Error with code and codeName properties', async () => {
+    const bundlePath = await createBundle({ encrypt: true, passphrase: 'secret' });
+    let caught: unknown = null;
+    try {
+      await unpackBundle({ bundlePath });
+    } catch (err) {
+      caught = err;
+    }
+    expect(caught).toBeInstanceOf(BundleError);
+    expect(caught).toBeInstanceOf(Error);
+    const be = caught as BundleError;
+    expect(typeof be.code).toBe('number');
+    expect(typeof be.codeName).toBe('string');
+    expect(be.name).toBe('BundleError');
+  });
+
+  // -------------------------------------------------------------------------
+  // Cleanup on error — staging dir is removed when unpack fails
+  // -------------------------------------------------------------------------
+
+  it('does not leave a staging dir behind when decryption fails', async () => {
+    const bundlePath = await createBundle({ encrypt: true, passphrase: 'secret' });
+    const preDirs = fs.readdirSync(os.tmpdir()).filter((n) => n.startsWith('cleo-unpack-'));
+
+    try {
+      await unpackBundle({ bundlePath, passphrase: 'wrong' });
+    } catch {
+      // expected
+    }
+
+    const postDirs = fs.readdirSync(os.tmpdir()).filter((n) => n.startsWith('cleo-unpack-'));
+    const newDirs = postDirs.filter((d) => !preDirs.includes(d));
+    expect(newDirs).toHaveLength(0);
+  });
+
+  // -------------------------------------------------------------------------
+  // Warnings are empty for a freshly-packed bundle
+  // -------------------------------------------------------------------------
+
+  it('returns no schema version warnings for a freshly packed bundle', async () => {
+    const bundlePath = await createBundle();
+    const result = await unpackBundle({ bundlePath });
+    // No warnings for a brand-new pack; schema versions may be 'unknown'
+    // so compareSchemaVersions returns null and warnings stays empty.
+    expect(Array.isArray(result.warnings)).toBe(true);
+    cleanupStaging(result.stagingDir);
+  });
+});