π The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
feat(encryption): ADR-096 Phase 4 β wire vault into memory DB writes/reads
Reuven841365f64568
diff --git a/v3/@claude-flow/cli/__tests__/memory-db-encryption.test.ts b/v3/@claude-flow/cli/__tests__/memory-db-encryption.test.tsnew file mode 100644index 0000000000..a2fae213d7--- /dev/null+++ b/v3/@claude-flow/cli/__tests__/memory-db-encryption.test.ts@@ -0,0 +1,198 @@+/**+ * Integration test for ADR-096 Phase 4: memory-initializer DB encryption.+ *+ * Different shape from session/terminal tests because the memory store is+ * a Buffer-only sql.js SQLite blob (not a JSON.stringify of an object).+ * The fs-secure helpers handle Buffer payloads identically β these tests+ * pin that contract end-to-end without spinning up the real sql.js+ * dependency (which has a heavy WASM init path).+ *+ * What's pinned:+ * - writeFileRestricted({encrypt:true}) on a Buffer payload produces+ * the RFE1 wire format when the env gate is on+ * - readFileMaybeEncrypted(path, null) returns a Buffer (not string)+ * and decrypts transparently when the file IS encrypted+ * - Round-trip: write Buffer β read Buffer matches byte-for-byte+ * - Migration: a legacy plaintext SQLite header on disk is still+ * readable after the gate flips on (magic-byte sniff returns false+ * for the SQLite header, so the file passes through unchanged)+ * - Tamper: a flipped byte inside an encrypted DB blob throws on read+ * rather than producing a corrupted Buffer+ */++import { afterEach, beforeEach, describe, expect, it } from 'vitest';+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join } from 'node:path';+import { randomBytes } from 'node:crypto';++import {+ readFileMaybeEncrypted,+ writeFileRestricted,+} from '../src/fs-secure.js';+import { MAGIC, isEncryptedBlob } from '../src/encryption/vault.js';++const SAVED_ENV: Record<string, string | undefined> = {};+function saveEnv(...names: string[]) {+ for (const n of names) SAVED_ENV[n] = process.env[n];+}+function restoreEnv() {+ for (const [n, v] of Object.entries(SAVED_ENV)) {+ if (v === undefined) delete process.env[n];+ else process.env[n] = v;+ }+}++// SQLite file format: first 16 bytes are "SQLite format 3\0". memory-initializer+// writes real sql.js exports (often multi-MB), but the encryption path doesn't+// care about content β only the Buffer shape. Use a plausible synthetic header+// + payload that exercises the same code path.+function makeSyntheticDbBuffer(payloadSize = 4096): Buffer {+ return Buffer.concat([+ Buffer.from('SQLite format 3\0', 'utf-8'),+ randomBytes(payloadSize - 16),+ ]);+}++describe('memory-initializer DB encryption (ADR-096 Phase 4)', () => {+ let workdir: string;+ let dbPath: string;++ beforeEach(() => {+ saveEnv('CLAUDE_FLOW_ENCRYPT_AT_REST', 'CLAUDE_FLOW_ENCRYPTION_KEY');+ workdir = mkdtempSync(join(tmpdir(), 'mem-db-enc-'));+ dbPath = join(workdir, 'memory.db');+ });++ afterEach(() => {+ rmSync(workdir, { recursive: true, force: true });+ restoreEnv();+ });++ describe('encryption disabled (legacy plaintext SQLite)', () => {+ beforeEach(() => {+ delete process.env.CLAUDE_FLOW_ENCRYPT_AT_REST;+ delete process.env.CLAUDE_FLOW_ENCRYPTION_KEY;+ });++ it('writes the SQLite buffer unchanged to disk', () => {+ const db = makeSyntheticDbBuffer();+ writeFileRestricted(dbPath, db, { encrypt: true });+ const onDisk = readFileSync(dbPath);+ expect(onDisk.equals(db)).toBe(true);+ // First 16 bytes are the literal SQLite header+ expect(onDisk.subarray(0, 16).toString('utf-8')).toBe('SQLite format 3\0');+ expect(isEncryptedBlob(onDisk)).toBe(false);+ });++ it('round-trips a Buffer through readFileMaybeEncrypted(path, null)', () => {+ const db = makeSyntheticDbBuffer();+ writeFileRestricted(dbPath, db, { encrypt: true });+ const round = readFileMaybeEncrypted(dbPath, null);+ expect(Buffer.isBuffer(round)).toBe(true);+ expect(round.equals(db)).toBe(true);+ });+ });++ describe('encryption enabled (RFE1 wire format)', () => {+ beforeEach(() => {+ process.env.CLAUDE_FLOW_ENCRYPT_AT_REST = '1';+ process.env.CLAUDE_FLOW_ENCRYPTION_KEY = randomBytes(32).toString('hex');+ });++ it('writes a blob that starts with the RFE1 magic, NOT the SQLite header', () => {+ const db = makeSyntheticDbBuffer();+ writeFileRestricted(dbPath, db, { encrypt: true });+ const onDisk = readFileSync(dbPath);+ expect(onDisk.subarray(0, 4)).toEqual(MAGIC);+ // Critical: the SQLite header must NOT appear at offset 0 β the+ // encryption ran and replaced the on-disk bytes.+ expect(onDisk.subarray(0, 16).toString('utf-8')).not.toBe('SQLite format 3\0');+ expect(isEncryptedBlob(onDisk)).toBe(true);+ });++ it('round-trips a Buffer through write β read with the same key', () => {+ const db = makeSyntheticDbBuffer();+ writeFileRestricted(dbPath, db, { encrypt: true });+ const round = readFileMaybeEncrypted(dbPath, null);+ expect(Buffer.isBuffer(round)).toBe(true);+ expect(round.equals(db)).toBe(true);+ });++ it('round-trips a megabyte-scale buffer (real-world memory.db size)', () => {+ const db = makeSyntheticDbBuffer(1_048_576); // 1MB+ writeFileRestricted(dbPath, db, { encrypt: true });+ const round = readFileMaybeEncrypted(dbPath, null);+ expect(round.equals(db)).toBe(true);+ });++ it('does not leak embedding-bytes into the on-disk blob', () => {+ // Plant a recognizable signature inside the synthetic DB and confirm+ // it does not appear in the encrypted bytes.+ const signature = Buffer.from('TOPSECRET-EMBEDDING-VECTOR-AAAA', 'utf-8');+ const db = Buffer.concat([+ Buffer.from('SQLite format 3\0', 'utf-8'),+ signature,+ randomBytes(2048),+ ]);+ writeFileRestricted(dbPath, db, { encrypt: true });+ const onDisk = readFileSync(dbPath);+ expect(onDisk.includes(signature)).toBe(false);+ });+ });++ describe('migration: legacy plaintext SQLite still readable', () => {+ it('plaintext SQLite written before the gate flipped on is returned as-is', () => {+ // Step 1: plant a plaintext SQLite blob on disk (no env vars set+ // β direct writeFileSync would normally have done this).+ const db = makeSyntheticDbBuffer();+ writeFileSync(dbPath, db);++ // Step 2: enable encryption for the read.+ process.env.CLAUDE_FLOW_ENCRYPT_AT_REST = '1';+ process.env.CLAUDE_FLOW_ENCRYPTION_KEY = randomBytes(32).toString('hex');++ // Step 3: readFileMaybeEncrypted's magic-byte sniff sees no RFE1+ // prefix, so it returns the Buffer unchanged. New SQL.Database()+ // would accept it directly.+ const round = readFileMaybeEncrypted(dbPath, null);+ expect(round.equals(db)).toBe(true);+ expect(round.subarray(0, 16).toString('utf-8')).toBe('SQLite format 3\0');+ });+ });++ describe('tamper detection on encrypted DB', () => {+ beforeEach(() => {+ process.env.CLAUDE_FLOW_ENCRYPT_AT_REST = '1';+ process.env.CLAUDE_FLOW_ENCRYPTION_KEY = randomBytes(32).toString('hex');+ });++ it('rejects a flipped ciphertext byte (GCM auth fails)', () => {+ const db = makeSyntheticDbBuffer();+ writeFileRestricted(dbPath, db, { encrypt: true });+ // Flip a byte deep inside the ciphertext region (after magic+iv,+ // before the trailing 16-byte tag)+ const bytes = readFileSync(dbPath);+ bytes[100] ^= 0xff;+ writeFileSync(dbPath, bytes);+ expect(() => readFileMaybeEncrypted(dbPath, null)).toThrow();+ });++ it('rejects a flipped magic byte (caught early with bad-magic error)', () => {+ const db = makeSyntheticDbBuffer();+ writeFileRestricted(dbPath, db, { encrypt: true });+ const bytes = readFileSync(dbPath);+ bytes[0] = 0x00;+ writeFileSync(dbPath, bytes);+ // The magic-sniff returns false (not RFE1 prefix anymore), so the+ // reader returns the bytes as-is. NB: this is the legacy-plaintext+ // path β the bytes are unreadable as SQLite but won't throw at the+ // fs-secure layer. That's correct: tamper detection on plaintext+ // SQLite is sql.js's job, not ours. The auth failure mode (above)+ // covers the case where the magic IS still RFE1 but content is bad.+ const round = readFileMaybeEncrypted(dbPath, null);+ expect(Buffer.isBuffer(round)).toBe(true);+ expect(round[0]).toBe(0x00); // tampered first byte propagates as-is+ });+ });+});diff --git a/v3/@claude-flow/cli/src/memory/memory-initializer.ts b/v3/@claude-flow/cli/src/memory/memory-initializer.tsindex 72dbdf0814..187bf9c1f4 100644--- a/v3/@claude-flow/cli/src/memory/memory-initializer.ts+++ b/v3/@claude-flow/cli/src/memory/memory-initializer.ts@@ -11,7 +11,7 @@import * as fs from 'fs';import * as path from 'path';-import { writeFileRestricted } from '../fs-secure.js';+import { readFileMaybeEncrypted, writeFileRestricted } from '../fs-secure.js';// ADR-053: Lazy import of AgentDB v3 bridgelet _bridge: typeof import('./memory-bridge.js') | null | undefined;@@ -440,7 +440,7 @@ export async function getHNSWIndex(options?: {try {const initSqlJs = (await import('sql.js')).default;const SQL = await initSqlJs();- const fileBuffer = fs.readFileSync(dbPath);+ const fileBuffer = readFileMaybeEncrypted(dbPath, null);const sqlDb = new SQL.Database(fileBuffer);// Load all entries with embeddings@@ -980,7 +980,7 @@ export async function ensureSchemaColumns(dbPath: string): Promise<{const initSqlJs = (await import('sql.js')).default;const SQL = await initSqlJs();- const fileBuffer = fs.readFileSync(dbPath);+ const fileBuffer = readFileMaybeEncrypted(dbPath, null);const db = new SQL.Database(fileBuffer);// Get current columns in memory_entries@@ -1022,7 +1022,7 @@ export async function ensureSchemaColumns(dbPath: string): Promise<{if (modified) {// Save updated databaseconst data = db.export();- writeFileRestricted(dbPath, Buffer.from(data));+ writeFileRestricted(dbPath, Buffer.from(data), { encrypt: true });}db.close();@@ -1238,7 +1238,7 @@ export async function initializeMemoryDatabase(options: {// Save to fileconst data = db.export();const buffer = Buffer.from(data);- writeFileRestricted(dbPath, buffer);+ writeFileRestricted(dbPath, buffer, { encrypt: true });// Close databasedb.close();@@ -1309,7 +1309,7 @@ export async function initializeMemoryDatabase(options: {sqliteHeader[26] = 0x20; // min embedded payloadsqliteHeader[27] = 0x20; // leaf payload- writeFileRestricted(dbPath, sqliteHeader);+ writeFileRestricted(dbPath, sqliteHeader, { encrypt: true });// ADR-053: Activate ControllerRegistry even on fallback pathconst controllerResult = await activateControllerRegistry(dbPath, verbose);@@ -1868,7 +1868,7 @@ export async function verifyMemoryInit(dbPath: string, options?: {const fs = await import('fs');// Load database- const fileBuffer = fs.readFileSync(dbPath);+ const fileBuffer = readFileMaybeEncrypted(dbPath, null);const db = new SQL.Database(fileBuffer);// Test 1: Schema verification@@ -2013,7 +2013,7 @@ export async function verifyMemoryInit(dbPath: string, options?: {// Save changesconst data = db.export();- writeFileRestricted(dbPath, Buffer.from(data));+ writeFileRestricted(dbPath, Buffer.from(data), { encrypt: true });db.close();const passed = tests.filter(t => t.passed).length;@@ -2105,7 +2105,7 @@ export async function storeEntry(options: {const initSqlJs = (await import('sql.js')).default;const SQL = await initSqlJs();- const fileBuffer = fs.readFileSync(dbPath);+ const fileBuffer = readFileMaybeEncrypted(dbPath, null);const db = new SQL.Database(fileBuffer);const id = `entry_${Date.now()}_${Math.random().toString(36).substring(7)}`;@@ -2153,7 +2153,7 @@ export async function storeEntry(options: {// Saveconst data = db.export();- writeFileRestricted(dbPath, Buffer.from(data));+ writeFileRestricted(dbPath, Buffer.from(data), { encrypt: true });db.close();// Add to HNSW index for faster future searches@@ -2244,7 +2244,7 @@ export async function searchEntries(options: {// Rerank candidates with exact cosine similarity from SQLiteconst initSqlJs = (await import('sql.js')).default;const SQL = await initSqlJs();- const fileBuffer = fs.readFileSync(dbPath);+ const fileBuffer = readFileMaybeEncrypted(dbPath, null);const db = new SQL.Database(fileBuffer);const reranked: { id: string; key: string; content: string; score: number; namespace: string }[] = [];@@ -2297,7 +2297,7 @@ export async function searchEntries(options: {const initSqlJs = (await import('sql.js')).default;const SQL = await initSqlJs();- const fileBuffer = fs.readFileSync(dbPath);+ const fileBuffer = readFileMaybeEncrypted(dbPath, null);const db = new SQL.Database(fileBuffer);// Get entries with embeddings@@ -2451,7 +2451,7 @@ export async function listEntries(options: {const initSqlJs = (await import('sql.js')).default;const SQL = await initSqlJs();- const fileBuffer = fs.readFileSync(dbPath);+ const fileBuffer = readFileMaybeEncrypted(dbPath, null);const db = new SQL.Database(fileBuffer);// Get total count@@ -2579,7 +2579,7 @@ export async function getEntry(options: {const initSqlJs = (await import('sql.js')).default;const SQL = await initSqlJs();- const fileBuffer = fs.readFileSync(dbPath);+ const fileBuffer = readFileMaybeEncrypted(dbPath, null);const db = new SQL.Database(fileBuffer);// Find entry by key@@ -2617,7 +2617,7 @@ export async function getEntry(options: {// Save updated databaseconst data = db.export();- writeFileRestricted(dbPath, Buffer.from(data));+ writeFileRestricted(dbPath, Buffer.from(data), { encrypt: true });db.close();@@ -2720,7 +2720,7 @@ export async function deleteEntry(options: {const initSqlJs = (await import('sql.js')).default;const SQL = await initSqlJs();- const fileBuffer = fs.readFileSync(dbPath);+ const fileBuffer = readFileMaybeEncrypted(dbPath, null);const db = new SQL.Database(fileBuffer);// Check if entry exists first@@ -2775,7 +2775,7 @@ export async function deleteEntry(options: {// Save updated databaseconst data = db.export();- writeFileRestricted(dbPath, Buffer.from(data));+ writeFileRestricted(dbPath, Buffer.from(data), { encrypt: true });db.close();