feat(encryption): ADR-096 Phase 4 — wire vault into memory DB writes/reads

Closes the high-tier encrypt-at-rest target trio (Phase 2 sessions,
Phase 3 terminals, Phase 4 memory DB). All three are now opt-in
encrypted under CLAUDE_FLOW_ENCRYPT_AT_REST without breaking any
existing test or callsite.

Memory DB is the largest of the three: a sql.js SQLite blob with
384-dim ONNX embeddings, often multi-MB. Different shape from the
JSON.stringify writers — pure Buffer in both directions.

Wired in src/memory/memory-initializer.ts:

  Reads — 9 sites converted from `fs.readFileSync(dbPath)` to
  `readFileMaybeEncrypted(dbPath, null)` (Buffer overload). Magic-
  byte sniff handles legacy plaintext + post-migration encrypted in
  the same call.

  Writes — 7 sites converted from `writeFileRestricted(dbPath, buf)`
  to `writeFileRestricted(dbPath, buf, { encrypt: true })`. Vault
  env-gate decides whether bytes are actually encrypted; off-by-default
  preserves the bit-for-bit legacy path.

Tests (__tests__/memory-db-encryption.test.ts, 9 cases):

  encryption disabled
    - SQLite buffer written unchanged (first 16 bytes are the literal
      "SQLite format 3\0" header)
    - readFileMaybeEncrypted(path, null) returns Buffer; round-trip OK

  encryption enabled
    - on-disk blob starts with RFE1 magic, NOT the SQLite header —
      pins that encryption actually replaced the bytes (regression
      sentinel)
    - round-trip with the same key
    - 1MB-scale round-trip (real-world memory.db size)
    - planted "TOPSECRET-EMBEDDING-VECTOR" signature does NOT appear
      in the encrypted bytes (defense-in-depth assertion)

  migration
    - plaintext SQLite written before the gate flipped is returned
      as-is via the magic-byte sniff (gate-on, file-off scenario)

  tamper
    - flipped ciphertext byte → GCM auth fails → throws on read
    - flipped magic byte → no longer detected as encrypted, returned
      as-is (correct: tamper on plaintext SQLite is sql.js's domain,
      not fs-secure's)

Verified:
  tsc --noEmit clean (0 errors)
  Encryption-track suite (vault + fs-secure + session + terminal +
    memory-db): 76/76 passing
  Full vitest suite: 1933/1933 passing, 46 skipped, 0 failures
    (was 1924; +9 from this commit)

ADR-096 high-tier scope is now complete. Phase 5 would extend to
medium-tier stores (agents/, tasks/, github/, etc.) but those have
much lower information value per the ADR's tiering and ship as a
separate decision.

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
+    });
+  });
+});

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();