Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 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

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.ts
new file mode 100644
index 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.ts
index 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 bridge
let _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 database
const 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 file
const data = db.export();
const buffer = Buffer.from(data);
- writeFileRestricted(dbPath, buffer);
+ writeFileRestricted(dbPath, buffer, { encrypt: true });
// Close database
db.close();
@@ -1309,7 +1309,7 @@ export async function initializeMemoryDatabase(options: {
sqliteHeader[26] = 0x20; // min embedded payload
sqliteHeader[27] = 0x20; // leaf payload
- writeFileRestricted(dbPath, sqliteHeader);
+ writeFileRestricted(dbPath, sqliteHeader, { encrypt: true });
// ADR-053: Activate ControllerRegistry even on fallback path
const 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 changes
const 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: {
// Save
const 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 SQLite
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 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 database
const 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 database
const data = db.export();
- writeFileRestricted(dbPath, Buffer.from(data));
+ writeFileRestricted(dbPath, Buffer.from(data), { encrypt: true });
db.close();