claude-flow 3.6.23 → 3.6.25

package/README.md

@@ -340,9 +340,15 @@ User --> Claude Code / CLI
 
 ## Documentation
 
-Full documentation including architecture, configuration, CLI reference, API usage, plugin development, and advanced topics:
+Three docs for three audiences:
 
-**[User Guide](docs/USERGUIDE.md)** -- Complete reference documentation
+| Doc | When to read it |
+|-----|-----------------|
+| **[Status](docs/STATUS.md)** | See what currently works — capability counts, test baselines, recent fixes, what's next. The *is-it-ready* doc. |
+| **[User Guide](docs/USERGUIDE.md)** | Daily reference — every command, every config flag, every plugin. The *how-do-I* doc. |
+| **[Verification](verification.md)** | Cryptographically prove your installed bytes match the signed witness — `ruflo verify`. The *trust-but-verify* doc. |
+
+User Guide section index:
 
 | Section | Topics |
 |---------|--------|

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-flow",
-  "version": "3.6.23",
+  "version": "3.6.25",
   "description": "Ruflo - Enterprise AI agent orchestration for Claude Code. Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration",
   "main": "dist/index.js",
   "type": "module",

package/v3/@claude-flow/cli/README.md

@@ -340,9 +340,15 @@ User --> Claude Code / CLI
 
 ## Documentation
 
-Full documentation including architecture, configuration, CLI reference, API usage, plugin development, and advanced topics:
+Three docs for three audiences:
 
-**[User Guide](docs/USERGUIDE.md)** -- Complete reference documentation
+| Doc | When to read it |
+|-----|-----------------|
+| **[Status](docs/STATUS.md)** | See what currently works — capability counts, test baselines, recent fixes, what's next. The *is-it-ready* doc. |
+| **[User Guide](docs/USERGUIDE.md)** | Daily reference — every command, every config flag, every plugin. The *how-do-I* doc. |
+| **[Verification](verification.md)** | Cryptographically prove your installed bytes match the signed witness — `ruflo verify`. The *trust-but-verify* doc. |
+
+User Guide section index:
 
 | Section | Topics |
 |---------|--------|

package/v3/@claude-flow/cli/bin/cli.js

@@ -54,10 +54,31 @@ if (isMCPMode) {
     `[${new Date().toISOString()}] INFO [claude-flow-mcp] (${sessionId}) Starting in stdio mode`
   );
 
+  // Audit-flagged DoS protection (audit_1776483149979): cap the
+  // newline-buffered stdin parser so a malicious client cannot pipe
+  // gigabytes of un-newlined data and exhaust memory before
+  // JSON.parse runs. 10MB is far above any legitimate MCP message
+  // (the protocol's largest realistic payloads — tool descriptions,
+  // batch search results — top out at ~1MB).
+  const MCP_MAX_BUFFER_BYTES = 10 * 1024 * 1024;
   let buffer = '';
   process.stdin.setEncoding('utf8');
   process.stdin.on('data', async (chunk) => {
     buffer += chunk;
+    if (buffer.length > MCP_MAX_BUFFER_BYTES) {
+      // Drop the buffer + emit a protocol-level error so the client
+      // sees the rejection rather than a silent OOM.
+      console.log(JSON.stringify({
+        jsonrpc: '2.0',
+        id: null,
+        error: {
+          code: -32700,
+          message: `Buffered stdin exceeds ${MCP_MAX_BUFFER_BYTES} bytes without newline; resetting`,
+        },
+      }));
+      buffer = '';
+      return;
+    }
     let lines = buffer.split('\n');
     buffer = lines.pop() || '';
 

package/v3/@claude-flow/cli/bin/mcp-server.js

@@ -48,12 +48,28 @@ console.error(JSON.stringify({
 }));
 
 // Handle stdin messages
+// Audit-flagged DoS protection (audit_1776483149979): cap stdin buffer
+// to 10MB. See bin/cli.js for the same protection on the auto-detect path.
+const MCP_MAX_BUFFER_BYTES = 10 * 1024 * 1024;
 let buffer = '';
 
 process.stdin.setEncoding('utf8');
 process.stdin.on('data', async (chunk) => {
   buffer += chunk;
 
+  if (buffer.length > MCP_MAX_BUFFER_BYTES) {
+    console.log(JSON.stringify({
+      jsonrpc: '2.0',
+      id: null,
+      error: {
+        code: -32700,
+        message: `Buffered stdin exceeds ${MCP_MAX_BUFFER_BYTES} bytes without newline; resetting`,
+      },
+    }));
+    buffer = '';
+    return;
+  }
+
   // Process complete JSON messages (newline-delimited)
   let lines = buffer.split('\n');
   buffer = lines.pop() || ''; // Keep incomplete line in buffer

package/v3/@claude-flow/cli/dist/src/commands/appliance.js

@@ -2,6 +2,8 @@
  * V3 CLI Appliance Command
  * Self-contained RVFA appliance management (build, inspect, verify, extract, run, sign, publish, update)
  */
+import { existsSync, mkdirSync, statSync } from 'node:fs';
+import { join as pathJoin, resolve as pathResolve } from 'node:path';
 import { output } from '../output.js';
 import { signCommand, publishCommand, updateAppCommand } from './appliance-advanced.js';
 function fmtSize(bytes) {
@@ -31,8 +33,7 @@ async function loadModule(path, exportName, label) {
     }
 }
 async function requireFile(file) {
-    const fs = await import('fs');
-    if (!fs.existsSync(file)) {
+    if (!existsSync(file)) {
         output.printError(`File not found: ${file}`);
         return false;
     }
@@ -171,8 +172,7 @@ const inspectCommand = {
             else {
                 output.writeln(output.dim('  No sections found'));
             }
-            const fs = await import('fs');
-            const stat = fs.statSync(file);
+            const stat = statSync(file);
             output.writeln();
             output.printInfo(`Total file size: ${output.bold(fmtSize(stat.size))}`);
             if (hdr.footerHash) {
@@ -269,14 +269,12 @@ const extractCommand = {
         if (!(await requireFile(file)))
             return { success: false, exitCode: 1 };
         try {
-            const fs = await import('fs');
-            const path = await import('path');
             header('RVFA Extraction');
             const reader = new RvfaReader(file);
             const hdr = await reader.parse();
-            const dest = path.resolve(outputDir);
-            if (!fs.existsSync(dest))
-                fs.mkdirSync(dest, { recursive: true });
+            const dest = pathResolve(outputDir);
+            if (!existsSync(dest))
+                mkdirSync(dest, { recursive: true });
             output.printInfo(`Destination: ${dest}`);
             output.writeln();
             if (sectionFilter) {
@@ -300,7 +298,7 @@ const extractCommand = {
             output.printSuccess(`Extraction complete: ${dest}`);
             output.writeln(output.dim('  Directory structure:'));
             for (const d of ['kernel', 'runtime', 'ruflo', 'models', 'data', 'verify']) {
-                const exists = fs.existsSync(path.join(dest, d));
+                const exists = existsSync(pathJoin(dest, d));
                 output.writeln(`  ${exists ? output.success('+') : output.dim('-')} ${d}/`);
             }
             return { success: true };

package/v3/@claude-flow/cli/dist/src/commands/guidance.js

@@ -2,6 +2,7 @@
  * V3 CLI Guidance Command
  * Guidance Control Plane - compile, retrieve, enforce, optimize
  */
+import { existsSync } from 'node:fs';
 import { output } from '../output.js';
 // compile subcommand
 const compileCommand = {
@@ -27,7 +28,6 @@ const compileCommand = {
         output.writeln(output.dim('─'.repeat(50)));
         try {
             const { readFile } = await import('node:fs/promises');
-            const { existsSync } = await import('node:fs');
             if (!existsSync(rootPath)) {
                 output.writeln(output.error(`Root guidance file not found: ${rootPath}`));
                 return { success: false, message: `File not found: ${rootPath}` };
@@ -107,7 +107,6 @@ const retrieveCommand = {
         output.writeln(output.dim('─'.repeat(50)));
         try {
             const { readFile } = await import('node:fs/promises');
-            const { existsSync } = await import('node:fs');
             const { GuidanceCompiler } = await import('@claude-flow/guidance/compiler');
             const { ShardRetriever, HashEmbeddingProvider } = await import('@claude-flow/guidance/retriever');
             if (!existsSync(rootPath)) {
@@ -262,7 +261,6 @@ const statusCommand = {
         output.writeln(output.bold('Guidance Control Plane Status'));
         output.writeln(output.dim('─'.repeat(50)));
         try {
-            const { existsSync } = await import('node:fs');
             const rootExists = existsSync('./CLAUDE.md');
             const localExists = existsSync('./CLAUDE.local.md');
             const statusData = {
@@ -332,7 +330,6 @@ const optimizeCommand = {
         output.writeln(output.dim('─'.repeat(50)));
         try {
             const { readFile, writeFile } = await import('node:fs/promises');
-            const { existsSync } = await import('node:fs');
             if (!existsSync(rootPath)) {
                 output.writeln(output.error(`Root guidance file not found: ${rootPath}`));
                 return { success: false, message: `File not found: ${rootPath}` };
@@ -433,7 +430,6 @@ const abTestCommand = {
         output.writeln(output.dim('─'.repeat(50)));
         try {
             const { readFile } = await import('node:fs/promises');
-            const { existsSync } = await import('node:fs');
             const { abBenchmark, getDefaultABTasks } = await import('@claude-flow/guidance/analyzer');
             // Load Config B (candidate) content
             if (!existsSync(configBPath)) {

package/v3/@claude-flow/cli/dist/src/commands/performance.js

@@ -4,6 +4,9 @@
  *
  * Created with ❤️ by ruv.io
  */
+import * as os from 'node:os';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
 import { output } from '../output.js';
 // Benchmark subcommand - REAL measurements
 const benchmarkCommand = {
@@ -299,9 +302,6 @@ const metricsCommand = {
         output.writeln();
         output.writeln(output.bold(`Performance Metrics (${timeframe})`));
         output.writeln(output.dim('─'.repeat(50)));
-        const os = await import('os');
-        const fs = await import('fs');
-        const path = await import('path');
         // Real system metrics
         const memUsage = process.memoryUsage();
         const cpuUsage = process.cpuUsage();

package/v3/@claude-flow/cli/dist/src/commands/process.js

@@ -2,7 +2,8 @@
  * V3 CLI Process Management Command
  * Background process management, daemon mode, and monitoring
  */
-import { writeFileSync, readFileSync, unlinkSync, existsSync, mkdirSync } from 'fs';
+import { readdirSync, writeFileSync, readFileSync, unlinkSync, existsSync, mkdirSync } from 'fs';
+import { cpus, loadavg, totalmem, freemem } from 'node:os';
 import { dirname, resolve } from 'path';
 // Helper functions for PID file management
 function writePidFile(pidFile, pid, port) {
@@ -238,11 +239,10 @@ const monitorCommand = {
         const watch = ctx.flags?.watch === true;
         const alerts = ctx.flags?.alerts !== false;
         // Gather real system metrics where possible
-        const os = await import('node:os');
         const memUsage = process.memoryUsage();
-        const loadAvg = os.loadavg();
-        const totalMem = os.totalmem();
-        const freeMem = os.freemem();
+        const loadAvg = loadavg();
+        const totalMem = totalmem();
+        const freeMem = freemem();
         const usedMemMB = Math.round((totalMem - freeMem) / 1024 / 1024);
         const totalMemMB = Math.round(totalMem / 1024 / 1024);
         // Try to read agent and task counts from local store files
@@ -280,7 +280,7 @@ const monitorCommand = {
             system: {
                 cpuLoadAvg1m: loadAvg[0] !== undefined ? parseFloat(loadAvg[0].toFixed(2)) : null,
                 cpuLoadAvg5m: loadAvg[1] !== undefined ? parseFloat(loadAvg[1].toFixed(2)) : null,
-                cpuCount: os.cpus().length,
+                cpuCount: cpus().length,
                 memoryUsedMB: usedMemMB,
                 memoryTotalMB: totalMemMB,
                 processRssMB: Math.round(memUsage.rss / 1024 / 1024),
@@ -607,7 +607,6 @@ const logsCommand = {
         const minLevelIdx = levels.indexOf(level);
         if (existsSync(logsDir)) {
             try {
-                const { readdirSync } = await import('node:fs');
                 const logFiles = readdirSync(logsDir)
                     .filter(f => f.endsWith('.log'))
                     .filter(f => source === 'all' || f.includes(source));

package/v3/@claude-flow/cli/dist/src/commands/verify.js

@@ -21,7 +21,9 @@ import { output } from '../output.js';
 const DEFAULT_MANIFEST_URL = 'https://raw.githubusercontent.com/ruvnet/ruflo/{branch}/verification.md.json';
 async function fetchWitness(branch) {
     const url = DEFAULT_MANIFEST_URL.replace('{branch}', branch);
-    const res = await fetch(url);
+    // audit_1776853149979: bare fetch had no timeout — a hung GitHub CDN would
+    // pin the verify command indefinitely. 30s is generous for a sub-MB JSON.
+    const res = await fetch(url, { signal: AbortSignal.timeout(30000) });
     if (!res.ok) {
         throw new Error(`Failed to fetch manifest from ${url}: ${res.status} ${res.statusText}`);
     }
@@ -48,12 +50,13 @@ function repoPathToInstalledPath(repoPath) {
     if (match) {
         const pkg = match[1];
         const rest = match[2];
-        // Try several anchors: cwd/node_modules, the dirname of this script's package
         const candidates = [];
+        // 1. cwd/node_modules/<pkg>/<rest> (typical end-user install)
         candidates.push(join(process.cwd(), 'node_modules', pkg, rest));
+        // 2. Walk up from this script looking for node_modules/<pkg>/<rest>
+        //    Covers cases where verify runs from inside a nested module.
         try {
             const __filename = fileURLToPath(import.meta.url);
-            // Walk up looking for node_modules
             let dir = dirname(__filename);
             for (let i = 0; i < 10; i++) {
                 candidates.push(join(dir, 'node_modules', pkg, rest));
@@ -64,6 +67,24 @@ function repoPathToInstalledPath(repoPath) {
             }
         }
         catch { /* ignore */ }
+        // 3. Source-tree resolution: when verify runs against a checked-out
+        //    repo (the developer's working copy), packages live at
+        //    `<repoRoot>/v3/<pkg>/<rest>` rather than under node_modules.
+        //    Walk up looking for the literal repo-relative path so the verify
+        //    command works for maintainers running it from the repo itself.
+        try {
+            const __filename = fileURLToPath(import.meta.url);
+            let dir = dirname(__filename);
+            for (let i = 0; i < 10; i++) {
+                candidates.push(join(dir, repoPath));
+                const parent = dirname(dir);
+                if (parent === dir)
+                    break;
+                dir = parent;
+            }
+        }
+        catch { /* ignore */ }
+        candidates.push(join(process.cwd(), repoPath));
         for (const c of candidates) {
             if (existsSync(c))
                 return c;

package/v3/@claude-flow/cli/dist/src/encryption/vault.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Encryption-at-rest vault primitives (ADR-096 Phase 1).
+ *
+ * Goal: provide deterministic encrypt/decrypt of arbitrary Buffers with a
+ * symmetric key, using a magic-byte format so readers of older plaintext
+ * stores can detect-then-pass-through during the migration window.
+ *
+ * Phase 1 deliberately ships only the cipher primitives + the env-var key
+ * source. Keychain (keytar) and interactive passphrase resolution land in
+ * a follow-up iteration so the blast radius of this commit is limited to
+ * a single self-contained module with no native dependencies.
+ *
+ * Wire format (output of encryptBuffer):
+ *
+ *   +---------+-----------+----------------+--------+
+ *   | magic 4 |   iv 12   |  ciphertext N  | tag 16 |
+ *   +---------+-----------+----------------+--------+
+ *      "RFE1"   random       AES-256-GCM     GCM
+ *
+ * The magic distinguishes encrypted blobs from plaintext during the
+ * incremental migration: readers call isEncryptedBlob() and either
+ * decryptBuffer() or treat the bytes as plaintext, so existing
+ * .claude-flow/sessions/*.json files keep working unchanged.
+ */
+/** ASCII "RFE1" — Ruflo File Encrypted v1. 4 bytes. */
+export declare const MAGIC: Buffer<ArrayBuffer>;
+/**
+ * True when at-rest encryption should be applied to writes.
+ *
+ * Truthy values: "1", "true", "yes", "on" (case-insensitive). Anything else
+ * — including unset — keeps the legacy plaintext path. This is the gate
+ * that lets the 1865-test baseline keep passing unchanged while users opt
+ * into encryption.
+ */
+export declare function isEncryptionEnabled(): boolean;
+/**
+ * Resolve a 32-byte encryption key from CLAUDE_FLOW_ENCRYPTION_KEY.
+ *
+ * Phase 1 supports only the env-var source; keychain and passphrase
+ * resolution are deferred to a follow-up iteration (see ADR-096). When
+ * encryption is enabled but no key resolves, this throws with a clear
+ * message rather than silently falling back to plaintext (fail-closed).
+ *
+ * Accepted encodings (auto-detected by length):
+ *   - 64-char hex (32 bytes)
+ *   - 44-char base64 (32 bytes + padding)
+ *   - exactly 32 raw bytes (rare; for callers that pre-decode)
+ *
+ * Anything else is rejected — we'd rather fail loudly than encrypt with a
+ * truncated key.
+ */
+export declare function getKey(): Buffer;
+/**
+ * Decode a key string. Exposed for testing and for the future passphrase
+ * resolver, which will scrypt-derive a Buffer and hand it back through here
+ * to share the same length-check.
+ */
+export declare function decodeKey(raw: string): Buffer;
+/**
+ * Encrypt a plaintext Buffer with AES-256-GCM. Returns the wire-format
+ * blob: magic(4) || iv(12) || ciphertext(N) || tag(16).
+ *
+ * The IV is freshly randomized per call. Reusing a (key, iv) pair under
+ * GCM is catastrophic — every call MUST produce a different IV. Node's
+ * randomBytes is csprng-backed so this is automatic; the function takes
+ * no IV input deliberately.
+ */
+export declare function encryptBuffer(plaintext: Buffer, key: Buffer): Buffer;
+/**
+ * Decrypt a wire-format blob. Verifies the magic byte (sanity), parses
+ * iv + ciphertext + tag, runs AES-256-GCM decrypt, and lets the GCM
+ * auth tag fail loudly on tamper (Node throws "Unsupported state or
+ * unable to authenticate data" — we let that propagate).
+ *
+ * Pre-condition: caller has already determined this is an encrypted
+ * blob via isEncryptedBlob(). decryptBuffer throws on bad magic so a
+ * mistaken plaintext blob still fails loudly rather than producing
+ * garbage.
+ */
+export declare function decryptBuffer(blob: Buffer, key: Buffer): Buffer;
+/**
+ * Magic-byte sniff. True iff the blob starts with the RFE1 magic AND is
+ * long enough to be a valid encrypted blob. Used by readers during the
+ * incremental migration: legacy plaintext files return false and flow
+ * through the existing read path unchanged.
+ *
+ * Note: this is a heuristic. A plaintext file that happens to start with
+ * "RFE1" would be misdetected — we accept that vanishingly small risk
+ * because (a) the four bytes 0x52,0x46,0x45,0x31 are an unusual prefix
+ * for JSON (`{`, `[`) or SQLite (`SQLite format 3`), and (b) decryption
+ * will then fail with a clear error rather than silently corrupt.
+ */
+export declare function isEncryptedBlob(blob: Buffer): boolean;
+//# sourceMappingURL=vault.d.ts.map

package/v3/@claude-flow/cli/dist/src/encryption/vault.js

@@ -0,0 +1,172 @@
+/**
+ * Encryption-at-rest vault primitives (ADR-096 Phase 1).
+ *
+ * Goal: provide deterministic encrypt/decrypt of arbitrary Buffers with a
+ * symmetric key, using a magic-byte format so readers of older plaintext
+ * stores can detect-then-pass-through during the migration window.
+ *
+ * Phase 1 deliberately ships only the cipher primitives + the env-var key
+ * source. Keychain (keytar) and interactive passphrase resolution land in
+ * a follow-up iteration so the blast radius of this commit is limited to
+ * a single self-contained module with no native dependencies.
+ *
+ * Wire format (output of encryptBuffer):
+ *
+ *   +---------+-----------+----------------+--------+
+ *   | magic 4 |   iv 12   |  ciphertext N  | tag 16 |
+ *   +---------+-----------+----------------+--------+
+ *      "RFE1"   random       AES-256-GCM     GCM
+ *
+ * The magic distinguishes encrypted blobs from plaintext during the
+ * incremental migration: readers call isEncryptedBlob() and either
+ * decryptBuffer() or treat the bytes as plaintext, so existing
+ * .claude-flow/sessions/*.json files keep working unchanged.
+ */
+import { createCipheriv, createDecipheriv, randomBytes, timingSafeEqual, } from 'node:crypto';
+// ── Constants ────────────────────────────────────────────────────────────────
+/** ASCII "RFE1" — Ruflo File Encrypted v1. 4 bytes. */
+export const MAGIC = Buffer.from([0x52, 0x46, 0x45, 0x31]); // "RFE1"
+const MAGIC_LEN = MAGIC.length; // 4
+const IV_LEN = 12; // GCM-recommended nonce size
+const TAG_LEN = 16; // GCM auth tag
+const KEY_LEN = 32; // AES-256
+const ALG = 'aes-256-gcm';
+const MIN_BLOB_LEN = MAGIC_LEN + IV_LEN + TAG_LEN; // empty plaintext still has these
+const ENV_ENABLE_FLAG = 'CLAUDE_FLOW_ENCRYPT_AT_REST';
+const ENV_KEY_VAR = 'CLAUDE_FLOW_ENCRYPTION_KEY';
+// ── Public API ───────────────────────────────────────────────────────────────
+/**
+ * True when at-rest encryption should be applied to writes.
+ *
+ * Truthy values: "1", "true", "yes", "on" (case-insensitive). Anything else
+ * — including unset — keeps the legacy plaintext path. This is the gate
+ * that lets the 1865-test baseline keep passing unchanged while users opt
+ * into encryption.
+ */
+export function isEncryptionEnabled() {
+    const v = process.env[ENV_ENABLE_FLAG];
+    if (typeof v !== 'string')
+        return false;
+    const norm = v.trim().toLowerCase();
+    return norm === '1' || norm === 'true' || norm === 'yes' || norm === 'on';
+}
+/**
+ * Resolve a 32-byte encryption key from CLAUDE_FLOW_ENCRYPTION_KEY.
+ *
+ * Phase 1 supports only the env-var source; keychain and passphrase
+ * resolution are deferred to a follow-up iteration (see ADR-096). When
+ * encryption is enabled but no key resolves, this throws with a clear
+ * message rather than silently falling back to plaintext (fail-closed).
+ *
+ * Accepted encodings (auto-detected by length):
+ *   - 64-char hex (32 bytes)
+ *   - 44-char base64 (32 bytes + padding)
+ *   - exactly 32 raw bytes (rare; for callers that pre-decode)
+ *
+ * Anything else is rejected — we'd rather fail loudly than encrypt with a
+ * truncated key.
+ */
+export function getKey() {
+    const raw = process.env[ENV_KEY_VAR];
+    if (!raw) {
+        throw new Error(`${ENV_ENABLE_FLAG} is set but ${ENV_KEY_VAR} is not. ` +
+            `Provide a 32-byte key as 64-char hex or 44-char base64. ` +
+            `See ADR-096 for keychain/passphrase support (coming in a follow-up).`);
+    }
+    return decodeKey(raw);
+}
+/**
+ * Decode a key string. Exposed for testing and for the future passphrase
+ * resolver, which will scrypt-derive a Buffer and hand it back through here
+ * to share the same length-check.
+ */
+export function decodeKey(raw) {
+    const trimmed = raw.trim();
+    // Hex first — strict 64 chars [0-9a-fA-F]
+    if (/^[0-9a-fA-F]{64}$/.test(trimmed)) {
+        return Buffer.from(trimmed, 'hex');
+    }
+    // Base64 — accept padded 44-char or unpadded 43-char forms
+    if (/^[A-Za-z0-9+/]{43}=?$/.test(trimmed)) {
+        const buf = Buffer.from(trimmed, 'base64');
+        if (buf.length === KEY_LEN)
+            return buf;
+    }
+    throw new Error(`Invalid ${ENV_KEY_VAR}: expected 32-byte key as 64-char hex or 44-char base64`);
+}
+/**
+ * Encrypt a plaintext Buffer with AES-256-GCM. Returns the wire-format
+ * blob: magic(4) || iv(12) || ciphertext(N) || tag(16).
+ *
+ * The IV is freshly randomized per call. Reusing a (key, iv) pair under
+ * GCM is catastrophic — every call MUST produce a different IV. Node's
+ * randomBytes is csprng-backed so this is automatic; the function takes
+ * no IV input deliberately.
+ */
+export function encryptBuffer(plaintext, key) {
+    if (!Buffer.isBuffer(plaintext)) {
+        throw new TypeError('encryptBuffer: plaintext must be a Buffer');
+    }
+    if (!Buffer.isBuffer(key) || key.length !== KEY_LEN) {
+        throw new TypeError(`encryptBuffer: key must be a ${KEY_LEN}-byte Buffer`);
+    }
+    const iv = randomBytes(IV_LEN);
+    const cipher = createCipheriv(ALG, key, iv);
+    const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return Buffer.concat([MAGIC, iv, ciphertext, tag]);
+}
+/**
+ * Decrypt a wire-format blob. Verifies the magic byte (sanity), parses
+ * iv + ciphertext + tag, runs AES-256-GCM decrypt, and lets the GCM
+ * auth tag fail loudly on tamper (Node throws "Unsupported state or
+ * unable to authenticate data" — we let that propagate).
+ *
+ * Pre-condition: caller has already determined this is an encrypted
+ * blob via isEncryptedBlob(). decryptBuffer throws on bad magic so a
+ * mistaken plaintext blob still fails loudly rather than producing
+ * garbage.
+ */
+export function decryptBuffer(blob, key) {
+    if (!Buffer.isBuffer(blob)) {
+        throw new TypeError('decryptBuffer: blob must be a Buffer');
+    }
+    if (!Buffer.isBuffer(key) || key.length !== KEY_LEN) {
+        throw new TypeError(`decryptBuffer: key must be a ${KEY_LEN}-byte Buffer`);
+    }
+    if (blob.length < MIN_BLOB_LEN) {
+        throw new Error(`decryptBuffer: blob too short (${blob.length}B; need >= ${MIN_BLOB_LEN}B)`);
+    }
+    const magic = blob.subarray(0, MAGIC_LEN);
+    // timingSafeEqual to avoid an oracle on the magic bytes specifically;
+    // not strictly required (the magic isn't secret) but cheap and correct.
+    if (!timingSafeEqual(magic, MAGIC)) {
+        throw new Error('decryptBuffer: bad magic — blob is not Ruflo-encrypted (RFE1)');
+    }
+    const iv = blob.subarray(MAGIC_LEN, MAGIC_LEN + IV_LEN);
+    const tag = blob.subarray(blob.length - TAG_LEN);
+    const ciphertext = blob.subarray(MAGIC_LEN + IV_LEN, blob.length - TAG_LEN);
+    const decipher = createDecipheriv(ALG, key, iv);
+    decipher.setAuthTag(tag);
+    return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+}
+/**
+ * Magic-byte sniff. True iff the blob starts with the RFE1 magic AND is
+ * long enough to be a valid encrypted blob. Used by readers during the
+ * incremental migration: legacy plaintext files return false and flow
+ * through the existing read path unchanged.
+ *
+ * Note: this is a heuristic. A plaintext file that happens to start with
+ * "RFE1" would be misdetected — we accept that vanishingly small risk
+ * because (a) the four bytes 0x52,0x46,0x45,0x31 are an unusual prefix
+ * for JSON (`{`, `[`) or SQLite (`SQLite format 3`), and (b) decryption
+ * will then fail with a clear error rather than silently corrupt.
+ */
+export function isEncryptedBlob(blob) {
+    if (!Buffer.isBuffer(blob))
+        return false;
+    if (blob.length < MIN_BLOB_LEN)
+        return false;
+    return timingSafeEqual(blob.subarray(0, MAGIC_LEN), MAGIC);
+}
+//# sourceMappingURL=vault.js.map

package/v3/@claude-flow/cli/dist/src/fs-secure.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Restricted-permission file helpers.
+ *
+ * audit_1776853149979: session/memory/terminal stores were written with the
+ * process umask, which on most macOS/Linux setups leaves them world-readable
+ * (mode 0644). They contain conversation snapshots, agent prompts, and
+ * terminal command history — anyone else on the host can read them.
+ *
+ * These helpers write atomically and force mode 0600 (files) / 0700 (dirs).
+ * chmod fails silently on Windows, where POSIX modes don't apply — that's
+ * fine, the OS-level ACL surface there is different.
+ *
+ * ADR-096 Phase 2: optional opt-in encryption-at-rest. When the caller
+ * passes `encrypt: true` AND the env-gated vault is enabled, payloads are
+ * AES-256-GCM-encrypted before hitting disk. Reads use the magic-byte
+ * sniff so legacy plaintext files keep working unchanged during the
+ * incremental migration.
+ */
+/**
+ * Create a directory tree with mode 0700 (owner-only). No-op if exists.
+ * Uses recursive: true so missing parents are created with the same mode.
+ */
+export declare function mkdirRestricted(path: string): void;
+/**
+ * Options for writeFileRestricted. Object form so we can grow the API
+ * without churning every call site.
+ */
+export interface WriteOptions {
+    /** Buffer encoding when `data` is a string. Ignored for Buffer payloads. */
+    encoding?: BufferEncoding;
+    /**
+     * If true AND encryption is globally enabled (CLAUDE_FLOW_ENCRYPT_AT_REST),
+     * encrypt the payload with AES-256-GCM before writing. If encryption is
+     * NOT enabled, this flag is silently ignored — the legacy plaintext path
+     * runs unchanged. Default: false.
+     */
+    encrypt?: boolean;
+}
+/**
+ * Write a file and tighten its permissions to mode 0600 (owner read/write).
+ *
+ * Two call signatures, both supported (the legacy positional one keeps
+ * existing call sites working without churn):
+ *
+ *   writeFileRestricted(path, data)                      // plaintext, utf-8
+ *   writeFileRestricted(path, data, 'utf-8')             // legacy: encoding only
+ *   writeFileRestricted(path, data, { encrypt: true })   // opt-in encryption
+ */
+export declare function writeFileRestricted(path: string, data: string | Buffer, optsOrEncoding?: BufferEncoding | WriteOptions): void;
+/**
+ * Read a file and transparently decrypt if it carries the RFE1 magic.
+ *
+ * Returns a string when the caller asks for one (default utf-8). Returns
+ * a Buffer when `encoding` is null. This matches Node's readFileSync
+ * shape so the function is a near-drop-in replacement.
+ *
+ * Migration semantics:
+ *   - If the file IS encrypted, decrypt and return.
+ *   - If the file is NOT encrypted, return its raw bytes (string-decoded
+ *     under `encoding` if requested).
+ *
+ * That means a reader can be migrated *first*, before its writer flips
+ * `encrypt: true`, without breaking on the legacy plaintext path.
+ */
+export declare function readFileMaybeEncrypted(path: string, encoding?: BufferEncoding): string;
+export declare function readFileMaybeEncrypted(path: string, encoding: null): Buffer;
+//# sourceMappingURL=fs-secure.d.ts.map