@cleocode/core 2026.4.12 → 2026.4.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/core",
-  "version": "2026.4.12",
+  "version": "2026.4.13",
   "description": "CLEO core business logic kernel — tasks, sessions, memory, orchestration, lifecycle, with bundled SQLite store",
   "type": "module",
   "main": "./dist/index.js",
@@ -32,15 +32,16 @@
     "pino": "^10.3.1",
     "pino-roll": "^4.0.0",
     "proper-lockfile": "^4.1.2",
+    "tar": "^7.4.3",
     "write-file-atomic": "^6.0.0",
     "yaml": "^2.8.2",
     "zod": "^3.25.76",
-    "@cleocode/adapters": "2026.4.12",
-    "@cleocode/agents": "2026.4.12",
-    "@cleocode/contracts": "2026.4.12",
-    "@cleocode/caamp": "2026.4.12",
-    "@cleocode/lafs": "2026.4.12",
-    "@cleocode/skills": "2026.4.12"
+    "@cleocode/adapters": "2026.4.13",
+    "@cleocode/agents": "2026.4.13",
+    "@cleocode/contracts": "2026.4.13",
+    "@cleocode/caamp": "2026.4.13",
+    "@cleocode/lafs": "2026.4.13",
+    "@cleocode/skills": "2026.4.13"
   },
   "optionalDependencies": {
     "tree-sitter-c": "^0.24.1",
@@ -70,6 +71,7 @@
   ],
   "devDependencies": {
     "@types/proper-lockfile": "^4.1.4",
+    "@types/tar": "^6.1.13",
     "@types/write-file-atomic": "^4.0.3"
   },
   "repository": {

package/src/internal.ts

@@ -410,6 +410,9 @@ export { listStickies, purgeSticky } from './sticky/index.js';
 export type { CreateStickyParams, ListStickiesParams, StickyNote } from './sticky/types.js';
 // Store
 export { createBackup, listBackups, restoreFromBackup } from './store/backup.js';
+// Backup portability — bundle packer (T311 / T347)
+export type { PackBundleInput, PackBundleResult } from './store/backup-pack.js';
+export { packBundle } from './store/backup-pack.js';
 export { getBrainDb, getBrainNativeDb } from './store/brain-sqlite.js';
 export type { LegacyCleanupResult, StrayNexusCleanupResult } from './store/cleanup-legacy.js';
 export {
@@ -442,7 +445,11 @@ export {
   SIGNALDOCK_SCHEMA_VERSION,
 } from './store/signaldock-sqlite.js';
 export { getDb, getNativeDb } from './store/sqlite.js';
-export type { BackupScope, GlobalBackupEntry, GlobalSaltBackupEntry } from './store/sqlite-backup.js';
+export type {
+  BackupScope,
+  GlobalBackupEntry,
+  GlobalSaltBackupEntry,
+} from './store/sqlite-backup.js';
 export {
   backupGlobalSalt,
   listBrainBackups,
@@ -696,11 +703,51 @@ export { readSnapshot } from './snapshot/index.js';
 export { addSticky } from './sticky/create.js';
 export { getSticky } from './sticky/index.js';
 
+// Store — backup crypto (T363)
+export { decryptBundle, encryptBundle, isEncryptedBundle } from './store/backup-crypto.js';
+
 // Store (additional)
 export { resolveProjectRoot } from './store/file-utils.js';
 export { TASK_PRIORITIES } from './store/tasks-schema.js';
 // System (additional)
 export type { MigrateResult } from './system/index.js';
+
+// ---------------------------------------------------------------------------
+// T311 Backup portability — unpack + verify + A/B restore (T350, T352, T354, T357)
+// ---------------------------------------------------------------------------
+
+// Unpack + verify (T350)
+export type {
+  SchemaCompatWarning as BundleSchemaCompatWarning,
+  UnpackBundleInput,
+  UnpackBundleResult,
+} from './store/backup-unpack.js';
+export { BundleError, cleanupStaging, unpackBundle } from './store/backup-unpack.js';
+// Dry-run JSON file generators (T352)
+export type { RegeneratedFile } from './store/regenerators.js';
+export {
+  regenerateAllJson,
+  regenerateConfigJson,
+  regenerateProjectContextJson,
+  regenerateProjectInfoJson,
+} from './store/regenerators.js';
+// Conflict report formatter (T357)
+export type {
+  BuildConflictReportInput,
+  ReauthWarning,
+  SchemaCompatWarning as RestoreSchemaCompatWarning,
+} from './store/restore-conflict-report.js';
+export { buildConflictReport, writeConflictReport } from './store/restore-conflict-report.js';
+// A/B regenerate-and-compare engine (T354)
+export type {
+  FieldCategory,
+  FieldClassification,
+  FilenameForRestore,
+  JsonRestoreReport,
+  RegenerateAndCompareInput,
+  Resolution,
+} from './store/restore-json-merge.js';
+export { regenerateAndCompare, regenerateAndCompareAll } from './store/restore-json-merge.js';
 // Tasks (additional — stats)
 export { coreTaskStats } from './tasks/task-ops.js';
 

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

@@ -0,0 +1,101 @@
+/**
+ * Unit tests for backup-crypto.ts (T345).
+ *
+ * Covers: round-trip correctness, magic/version header, ciphertext
+ * non-determinism (random salt + nonce), error paths (wrong passphrase,
+ * truncated payload, bit-flip tamper, magic mismatch, too-short), and
+ * isEncryptedBundle detection.
+ *
+ * @task T345
+ * @epic T311
+ */
+
+import crypto from 'node:crypto';
+import { describe, expect, it } from 'vitest';
+import { decryptBundle, encryptBundle, isEncryptedBundle } from '../backup-crypto.js';
+
+describe('backup-crypto', () => {
+  const plaintext = Buffer.from('Hello, CLEO backup world! 🌍 Non-ASCII: ñoño café');
+  const passphrase = 'correct horse battery staple';
+
+  it('round-trip: decrypt(encrypt(x)) == x', () => {
+    const encrypted = encryptBundle(plaintext, passphrase);
+    const decrypted = decryptBundle(encrypted, passphrase);
+    expect(decrypted.equals(plaintext)).toBe(true);
+  });
+
+  it('encryptBundle output starts with CLEOENC1 magic', () => {
+    const enc = encryptBundle(plaintext, passphrase);
+    expect(enc.subarray(0, 8).toString('utf8')).toBe('CLEOENC1');
+  });
+
+  it('encryptBundle output has version byte 0x01 at offset 8', () => {
+    const enc = encryptBundle(plaintext, passphrase);
+    expect(enc[8]).toBe(0x01);
+  });
+
+  it('two encryptions of same input differ (random salt + nonce)', () => {
+    const e1 = encryptBundle(plaintext, passphrase);
+    const e2 = encryptBundle(plaintext, passphrase);
+    expect(e1.equals(e2)).toBe(false);
+  });
+
+  it('decryptBundle throws on wrong passphrase', () => {
+    const enc = encryptBundle(plaintext, passphrase);
+    expect(() => decryptBundle(enc, 'wrong passphrase')).toThrow(/authentication failed/);
+  });
+
+  it('decryptBundle throws on truncated ciphertext (auth tag missing)', () => {
+    const enc = encryptBundle(plaintext, passphrase);
+    const truncated = enc.subarray(0, enc.length - 1);
+    expect(() => decryptBundle(truncated, passphrase)).toThrow();
+  });
+
+  it('decryptBundle throws on flipped bit (auth tag fails)', () => {
+    const enc = encryptBundle(plaintext, passphrase);
+    // Flip a byte in the middle of the ciphertext region
+    const tampered = Buffer.from(enc);
+    const idx = 16 + 32 + 12 + 5; // well inside ciphertext region
+    tampered[idx] ^= 0x01;
+    expect(() => decryptBundle(tampered, passphrase)).toThrow(/authentication failed/);
+  });
+
+  it('decryptBundle throws on magic mismatch', () => {
+    const bogus = Buffer.alloc(128);
+    expect(() => decryptBundle(bogus, passphrase)).toThrow(/magic mismatch/);
+  });
+
+  it('decryptBundle throws on payload too short', () => {
+    const tiny = Buffer.alloc(32);
+    expect(() => decryptBundle(tiny, passphrase)).toThrow(/too short/);
+  });
+
+  it('encryptBundle throws on empty passphrase', () => {
+    expect(() => encryptBundle(plaintext, '')).toThrow(/passphrase/);
+  });
+
+  it('isEncryptedBundle returns true for magic header', () => {
+    const enc = encryptBundle(plaintext, passphrase);
+    expect(isEncryptedBundle(enc.subarray(0, 8))).toBe(true);
+  });
+
+  it('isEncryptedBundle returns false for random data', () => {
+    const random = crypto.randomBytes(32);
+    expect(isEncryptedBundle(random)).toBe(false);
+  });
+
+  it('handles large payloads (1 MB)', () => {
+    const large = crypto.randomBytes(1024 * 1024);
+    const enc = encryptBundle(large, passphrase);
+    const dec = decryptBundle(enc, passphrase);
+    expect(dec.equals(large)).toBe(true);
+  });
+
+  it('scrypt derivation is deterministic for same passphrase + salt', () => {
+    // Indirectly verified: two independent round-trips both recover the plaintext.
+    const e1 = encryptBundle(plaintext, passphrase);
+    const e2 = encryptBundle(plaintext, passphrase);
+    expect(decryptBundle(e1, passphrase).equals(plaintext)).toBe(true);
+    expect(decryptBundle(e2, passphrase).equals(plaintext)).toBe(true);
+  });
+});