claude-flow 3.6.24 → 3.6.26

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (28) hide show
  1. package/README.md +8 -2
  2. package/package.json +1 -1
  3. package/v3/@claude-flow/cli/README.md +8 -2
  4. package/v3/@claude-flow/cli/bin/cli.js +21 -0
  5. package/v3/@claude-flow/cli/bin/mcp-server.js +16 -0
  6. package/v3/@claude-flow/cli/dist/src/commands/appliance.js +8 -10
  7. package/v3/@claude-flow/cli/dist/src/commands/doctor.js +90 -2
  8. package/v3/@claude-flow/cli/dist/src/commands/guidance.js +1 -5
  9. package/v3/@claude-flow/cli/dist/src/commands/performance.js +3 -3
  10. package/v3/@claude-flow/cli/dist/src/commands/process.js +6 -7
  11. package/v3/@claude-flow/cli/dist/src/commands/verify.js +24 -3
  12. package/v3/@claude-flow/cli/dist/src/encryption/vault.d.ts +94 -0
  13. package/v3/@claude-flow/cli/dist/src/encryption/vault.js +172 -0
  14. package/v3/@claude-flow/cli/dist/src/fs-secure.d.ts +67 -0
  15. package/v3/@claude-flow/cli/dist/src/fs-secure.js +74 -0
  16. package/v3/@claude-flow/cli/dist/src/mcp-tools/github-tools.js +122 -31
  17. package/v3/@claude-flow/cli/dist/src/mcp-tools/hooks-tools.js +2 -2
  18. package/v3/@claude-flow/cli/dist/src/mcp-tools/memory-tools.js +7 -12
  19. package/v3/@claude-flow/cli/dist/src/mcp-tools/session-tools.js +24 -12
  20. package/v3/@claude-flow/cli/dist/src/mcp-tools/terminal-tools.js +22 -7
  21. package/v3/@claude-flow/cli/dist/src/mcp-tools/validate-input.d.ts +12 -0
  22. package/v3/@claude-flow/cli/dist/src/mcp-tools/validate-input.js +56 -0
  23. package/v3/@claude-flow/cli/dist/src/memory/memory-initializer.js +17 -16
  24. package/v3/@claude-flow/cli/dist/src/transfer/ipfs/upload.js +2 -0
  25. package/v3/@claude-flow/cli/dist/src/update/executor.d.ts +1 -0
  26. package/v3/@claude-flow/cli/dist/src/update/executor.js +43 -7
  27. package/v3/@claude-flow/cli/package.json +1 -1
  28. package/.claude/scheduled_tasks.lock +0 -1
package/README.md CHANGED
@@ -340,9 +340,15 @@ User --> Claude Code / CLI
340
340
 
341
341
  ## Documentation
342
342
 
343
- Full documentation including architecture, configuration, CLI reference, API usage, plugin development, and advanced topics:
343
+ Three docs for three audiences:
344
344
 
345
- **[User Guide](docs/USERGUIDE.md)** -- Complete reference documentation
345
+ | Doc | When to read it |
346
+ |-----|-----------------|
347
+ | **[Status](docs/STATUS.md)** | See what currently works — capability counts, test baselines, recent fixes, what's next. The *is-it-ready* doc. |
348
+ | **[User Guide](docs/USERGUIDE.md)** | Daily reference — every command, every config flag, every plugin. The *how-do-I* doc. |
349
+ | **[Verification](verification.md)** | Cryptographically prove your installed bytes match the signed witness — `ruflo verify`. The *trust-but-verify* doc. |
350
+
351
+ User Guide section index:
346
352
 
347
353
  | Section | Topics |
348
354
  |---------|--------|
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "claude-flow",
3
- "version": "3.6.24",
3
+ "version": "3.6.26",
4
4
  "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",
5
5
  "main": "dist/index.js",
6
6
  "type": "module",
@@ -340,9 +340,15 @@ User --> Claude Code / CLI
340
340
 
341
341
  ## Documentation
342
342
 
343
- Full documentation including architecture, configuration, CLI reference, API usage, plugin development, and advanced topics:
343
+ Three docs for three audiences:
344
344
 
345
- **[User Guide](docs/USERGUIDE.md)** -- Complete reference documentation
345
+ | Doc | When to read it |
346
+ |-----|-----------------|
347
+ | **[Status](docs/STATUS.md)** | See what currently works — capability counts, test baselines, recent fixes, what's next. The *is-it-ready* doc. |
348
+ | **[User Guide](docs/USERGUIDE.md)** | Daily reference — every command, every config flag, every plugin. The *how-do-I* doc. |
349
+ | **[Verification](verification.md)** | Cryptographically prove your installed bytes match the signed witness — `ruflo verify`. The *trust-but-verify* doc. |
350
+
351
+ User Guide section index:
346
352
 
347
353
  | Section | Topics |
348
354
  |---------|--------|
@@ -54,10 +54,31 @@ if (isMCPMode) {
54
54
  `[${new Date().toISOString()}] INFO [claude-flow-mcp] (${sessionId}) Starting in stdio mode`
55
55
  );
56
56
 
57
+ // Audit-flagged DoS protection (audit_1776483149979): cap the
58
+ // newline-buffered stdin parser so a malicious client cannot pipe
59
+ // gigabytes of un-newlined data and exhaust memory before
60
+ // JSON.parse runs. 10MB is far above any legitimate MCP message
61
+ // (the protocol's largest realistic payloads — tool descriptions,
62
+ // batch search results — top out at ~1MB).
63
+ const MCP_MAX_BUFFER_BYTES = 10 * 1024 * 1024;
57
64
  let buffer = '';
58
65
  process.stdin.setEncoding('utf8');
59
66
  process.stdin.on('data', async (chunk) => {
60
67
  buffer += chunk;
68
+ if (buffer.length > MCP_MAX_BUFFER_BYTES) {
69
+ // Drop the buffer + emit a protocol-level error so the client
70
+ // sees the rejection rather than a silent OOM.
71
+ console.log(JSON.stringify({
72
+ jsonrpc: '2.0',
73
+ id: null,
74
+ error: {
75
+ code: -32700,
76
+ message: `Buffered stdin exceeds ${MCP_MAX_BUFFER_BYTES} bytes without newline; resetting`,
77
+ },
78
+ }));
79
+ buffer = '';
80
+ return;
81
+ }
61
82
  let lines = buffer.split('\n');
62
83
  buffer = lines.pop() || '';
63
84
 
@@ -48,12 +48,28 @@ console.error(JSON.stringify({
48
48
  }));
49
49
 
50
50
  // Handle stdin messages
51
+ // Audit-flagged DoS protection (audit_1776483149979): cap stdin buffer
52
+ // to 10MB. See bin/cli.js for the same protection on the auto-detect path.
53
+ const MCP_MAX_BUFFER_BYTES = 10 * 1024 * 1024;
51
54
  let buffer = '';
52
55
 
53
56
  process.stdin.setEncoding('utf8');
54
57
  process.stdin.on('data', async (chunk) => {
55
58
  buffer += chunk;
56
59
 
60
+ if (buffer.length > MCP_MAX_BUFFER_BYTES) {
61
+ console.log(JSON.stringify({
62
+ jsonrpc: '2.0',
63
+ id: null,
64
+ error: {
65
+ code: -32700,
66
+ message: `Buffered stdin exceeds ${MCP_MAX_BUFFER_BYTES} bytes without newline; resetting`,
67
+ },
68
+ }));
69
+ buffer = '';
70
+ return;
71
+ }
72
+
57
73
  // Process complete JSON messages (newline-delimited)
58
74
  let lines = buffer.split('\n');
59
75
  buffer = lines.pop() || ''; // Keep incomplete line in buffer
@@ -2,6 +2,8 @@
2
2
  * V3 CLI Appliance Command
3
3
  * Self-contained RVFA appliance management (build, inspect, verify, extract, run, sign, publish, update)
4
4
  */
5
+ import { existsSync, mkdirSync, statSync } from 'node:fs';
6
+ import { join as pathJoin, resolve as pathResolve } from 'node:path';
5
7
  import { output } from '../output.js';
6
8
  import { signCommand, publishCommand, updateAppCommand } from './appliance-advanced.js';
7
9
  function fmtSize(bytes) {
@@ -31,8 +33,7 @@ async function loadModule(path, exportName, label) {
31
33
  }
32
34
  }
33
35
  async function requireFile(file) {
34
- const fs = await import('fs');
35
- if (!fs.existsSync(file)) {
36
+ if (!existsSync(file)) {
36
37
  output.printError(`File not found: ${file}`);
37
38
  return false;
38
39
  }
@@ -171,8 +172,7 @@ const inspectCommand = {
171
172
  else {
172
173
  output.writeln(output.dim(' No sections found'));
173
174
  }
174
- const fs = await import('fs');
175
- const stat = fs.statSync(file);
175
+ const stat = statSync(file);
176
176
  output.writeln();
177
177
  output.printInfo(`Total file size: ${output.bold(fmtSize(stat.size))}`);
178
178
  if (hdr.footerHash) {
@@ -269,14 +269,12 @@ const extractCommand = {
269
269
  if (!(await requireFile(file)))
270
270
  return { success: false, exitCode: 1 };
271
271
  try {
272
- const fs = await import('fs');
273
- const path = await import('path');
274
272
  header('RVFA Extraction');
275
273
  const reader = new RvfaReader(file);
276
274
  const hdr = await reader.parse();
277
- const dest = path.resolve(outputDir);
278
- if (!fs.existsSync(dest))
279
- fs.mkdirSync(dest, { recursive: true });
275
+ const dest = pathResolve(outputDir);
276
+ if (!existsSync(dest))
277
+ mkdirSync(dest, { recursive: true });
280
278
  output.printInfo(`Destination: ${dest}`);
281
279
  output.writeln();
282
280
  if (sectionFilter) {
@@ -300,7 +298,7 @@ const extractCommand = {
300
298
  output.printSuccess(`Extraction complete: ${dest}`);
301
299
  output.writeln(output.dim(' Directory structure:'));
302
300
  for (const d of ['kernel', 'runtime', 'ruflo', 'models', 'data', 'verify']) {
303
- const exists = fs.existsSync(path.join(dest, d));
301
+ const exists = existsSync(pathJoin(dest, d));
304
302
  output.writeln(` ${exists ? output.success('+') : output.dim('-')} ${d}/`);
305
303
  }
306
304
  return { success: true };
@@ -8,8 +8,11 @@ import { output } from '../output.js';
8
8
  import { existsSync, readFileSync, statSync } from 'fs';
9
9
  import { join, dirname } from 'path';
10
10
  import { fileURLToPath } from 'url';
11
+ import { createHash } from 'crypto';
11
12
  import { execSync, exec } from 'child_process';
12
13
  import { promisify } from 'util';
14
+ import { decodeKey, isEncryptionEnabled } from '../encryption/vault.js';
15
+ import { isEncryptedBlob } from '../encryption/vault.js';
13
16
  // Promisified exec with proper shell and env inheritance for cross-platform support
14
17
  const execAsync = promisify(exec);
15
18
  /**
@@ -423,6 +426,89 @@ async function checkAgenticFlow() {
423
426
  return { name: 'agentic-flow', status: 'warn', message: 'Check failed' };
424
427
  }
425
428
  }
429
+ // Check encryption-at-rest status (ADR-096 Phase 5)
430
+ //
431
+ // Reports four facets without disclosing the key itself:
432
+ // 1. Gate status — is CLAUDE_FLOW_ENCRYPT_AT_REST set?
433
+ // 2. Key resolution — does CLAUDE_FLOW_ENCRYPTION_KEY resolve to a valid
434
+ // 32-byte key (env-var path only; keychain/passphrase are deferred)?
435
+ // 3. Key fingerprint — first 16 hex chars of sha256(key) so users can
436
+ // sanity-check across machines without ever logging the key bytes.
437
+ // 4. High-tier store presence — for sessions/, terminals/, .swarm/memory.db
438
+ // report whether on-disk bytes carry the RFE1 magic (encrypted) or not.
439
+ async function checkEncryptionAtRest() {
440
+ if (!isEncryptionEnabled()) {
441
+ return {
442
+ name: 'Encryption at Rest',
443
+ status: 'warn',
444
+ message: 'Off — session/terminal/memory stores are plaintext (mode 0600 only)',
445
+ fix: 'export CLAUDE_FLOW_ENCRYPT_AT_REST=1 && export CLAUDE_FLOW_ENCRYPTION_KEY=<64-char-hex>',
446
+ };
447
+ }
448
+ // Gate is on — try to resolve the key. Fail-closed if missing or malformed.
449
+ const rawKey = process.env.CLAUDE_FLOW_ENCRYPTION_KEY;
450
+ if (!rawKey) {
451
+ return {
452
+ name: 'Encryption at Rest',
453
+ status: 'fail',
454
+ message: 'Gate is on but CLAUDE_FLOW_ENCRYPTION_KEY is unset (fail-closed)',
455
+ fix: 'Generate a key: openssl rand -hex 32 → export CLAUDE_FLOW_ENCRYPTION_KEY=<value>',
456
+ };
457
+ }
458
+ let keyFingerprint;
459
+ try {
460
+ const key = decodeKey(rawKey);
461
+ keyFingerprint = createHash('sha256').update(key).digest('hex').slice(0, 16);
462
+ }
463
+ catch (err) {
464
+ return {
465
+ name: 'Encryption at Rest',
466
+ status: 'fail',
467
+ message: `CLAUDE_FLOW_ENCRYPTION_KEY invalid: ${err instanceof Error ? err.message : String(err)}`,
468
+ fix: 'Provide a 64-char hex or 44-char base64 key (32 bytes)',
469
+ };
470
+ }
471
+ // Check the three high-tier store paths for RFE1 magic
472
+ const cwd = process.cwd();
473
+ const stores = [
474
+ { label: 'sessions/', path: join(cwd, '.claude-flow', 'sessions') },
475
+ { label: 'terminals', path: join(cwd, '.claude-flow', 'terminals', 'store.json') },
476
+ { label: 'memory.db', path: join(cwd, '.swarm', 'memory.db') },
477
+ ];
478
+ const status = [];
479
+ for (const s of stores) {
480
+ if (!existsSync(s.path)) {
481
+ status.push(`${s.label}=∅`);
482
+ continue;
483
+ }
484
+ try {
485
+ const stat = statSync(s.path);
486
+ if (stat.isDirectory()) {
487
+ // Sessions: probe the first .json file
488
+ const { readdirSync } = await import('fs');
489
+ const files = readdirSync(s.path).filter(f => f.endsWith('.json'));
490
+ if (files.length === 0) {
491
+ status.push(`${s.label}=∅`);
492
+ continue;
493
+ }
494
+ const first = readFileSync(join(s.path, files[0]));
495
+ status.push(`${s.label}=${isEncryptedBlob(first) ? 'enc' : 'plain'}`);
496
+ }
497
+ else {
498
+ const buf = readFileSync(s.path);
499
+ status.push(`${s.label}=${isEncryptedBlob(buf) ? 'enc' : 'plain'}`);
500
+ }
501
+ }
502
+ catch {
503
+ status.push(`${s.label}=err`);
504
+ }
505
+ }
506
+ return {
507
+ name: 'Encryption at Rest',
508
+ status: 'pass',
509
+ message: `On — key fp:${keyFingerprint}… (${status.join(' ')})`,
510
+ };
511
+ }
426
512
  // Format health check result
427
513
  function formatCheck(check) {
428
514
  const icon = check.status === 'pass' ? output.success('✓') :
@@ -494,7 +580,8 @@ export const doctorCommand = {
494
580
  checkMcpServers,
495
581
  checkDiskSpace,
496
582
  checkBuildTools,
497
- checkAgenticFlow
583
+ checkAgenticFlow,
584
+ checkEncryptionAtRest, // ADR-096 Phase 5
498
585
  ];
499
586
  const componentMap = {
500
587
  'version': checkVersionFreshness,
@@ -510,7 +597,8 @@ export const doctorCommand = {
510
597
  'mcp': checkMcpServers,
511
598
  'disk': checkDiskSpace,
512
599
  'typescript': checkBuildTools,
513
- 'agentic-flow': checkAgenticFlow
600
+ 'agentic-flow': checkAgenticFlow,
601
+ 'encryption': checkEncryptionAtRest, // ADR-096 Phase 5
514
602
  };
515
603
  let checksToRun = allChecks;
516
604
  if (component && componentMap[component]) {
@@ -2,6 +2,7 @@
2
2
  * V3 CLI Guidance Command
3
3
  * Guidance Control Plane - compile, retrieve, enforce, optimize
4
4
  */
5
+ import { existsSync } from 'node:fs';
5
6
  import { output } from '../output.js';
6
7
  // compile subcommand
7
8
  const compileCommand = {
@@ -27,7 +28,6 @@ const compileCommand = {
27
28
  output.writeln(output.dim('─'.repeat(50)));
28
29
  try {
29
30
  const { readFile } = await import('node:fs/promises');
30
- const { existsSync } = await import('node:fs');
31
31
  if (!existsSync(rootPath)) {
32
32
  output.writeln(output.error(`Root guidance file not found: ${rootPath}`));
33
33
  return { success: false, message: `File not found: ${rootPath}` };
@@ -107,7 +107,6 @@ const retrieveCommand = {
107
107
  output.writeln(output.dim('─'.repeat(50)));
108
108
  try {
109
109
  const { readFile } = await import('node:fs/promises');
110
- const { existsSync } = await import('node:fs');
111
110
  const { GuidanceCompiler } = await import('@claude-flow/guidance/compiler');
112
111
  const { ShardRetriever, HashEmbeddingProvider } = await import('@claude-flow/guidance/retriever');
113
112
  if (!existsSync(rootPath)) {
@@ -262,7 +261,6 @@ const statusCommand = {
262
261
  output.writeln(output.bold('Guidance Control Plane Status'));
263
262
  output.writeln(output.dim('─'.repeat(50)));
264
263
  try {
265
- const { existsSync } = await import('node:fs');
266
264
  const rootExists = existsSync('./CLAUDE.md');
267
265
  const localExists = existsSync('./CLAUDE.local.md');
268
266
  const statusData = {
@@ -332,7 +330,6 @@ const optimizeCommand = {
332
330
  output.writeln(output.dim('─'.repeat(50)));
333
331
  try {
334
332
  const { readFile, writeFile } = await import('node:fs/promises');
335
- const { existsSync } = await import('node:fs');
336
333
  if (!existsSync(rootPath)) {
337
334
  output.writeln(output.error(`Root guidance file not found: ${rootPath}`));
338
335
  return { success: false, message: `File not found: ${rootPath}` };
@@ -433,7 +430,6 @@ const abTestCommand = {
433
430
  output.writeln(output.dim('─'.repeat(50)));
434
431
  try {
435
432
  const { readFile } = await import('node:fs/promises');
436
- const { existsSync } = await import('node:fs');
437
433
  const { abBenchmark, getDefaultABTasks } = await import('@claude-flow/guidance/analyzer');
438
434
  // Load Config B (candidate) content
439
435
  if (!existsSync(configBPath)) {
@@ -4,6 +4,9 @@
4
4
  *
5
5
  * Created with ❤️ by ruv.io
6
6
  */
7
+ import * as os from 'node:os';
8
+ import * as fs from 'node:fs';
9
+ import * as path from 'node:path';
7
10
  import { output } from '../output.js';
8
11
  // Benchmark subcommand - REAL measurements
9
12
  const benchmarkCommand = {
@@ -299,9 +302,6 @@ const metricsCommand = {
299
302
  output.writeln();
300
303
  output.writeln(output.bold(`Performance Metrics (${timeframe})`));
301
304
  output.writeln(output.dim('─'.repeat(50)));
302
- const os = await import('os');
303
- const fs = await import('fs');
304
- const path = await import('path');
305
305
  // Real system metrics
306
306
  const memUsage = process.memoryUsage();
307
307
  const cpuUsage = process.cpuUsage();
@@ -2,7 +2,8 @@
2
2
  * V3 CLI Process Management Command
3
3
  * Background process management, daemon mode, and monitoring
4
4
  */
5
- import { writeFileSync, readFileSync, unlinkSync, existsSync, mkdirSync } from 'fs';
5
+ import { readdirSync, writeFileSync, readFileSync, unlinkSync, existsSync, mkdirSync } from 'fs';
6
+ import { cpus, loadavg, totalmem, freemem } from 'node:os';
6
7
  import { dirname, resolve } from 'path';
7
8
  // Helper functions for PID file management
8
9
  function writePidFile(pidFile, pid, port) {
@@ -238,11 +239,10 @@ const monitorCommand = {
238
239
  const watch = ctx.flags?.watch === true;
239
240
  const alerts = ctx.flags?.alerts !== false;
240
241
  // Gather real system metrics where possible
241
- const os = await import('node:os');
242
242
  const memUsage = process.memoryUsage();
243
- const loadAvg = os.loadavg();
244
- const totalMem = os.totalmem();
245
- const freeMem = os.freemem();
243
+ const loadAvg = loadavg();
244
+ const totalMem = totalmem();
245
+ const freeMem = freemem();
246
246
  const usedMemMB = Math.round((totalMem - freeMem) / 1024 / 1024);
247
247
  const totalMemMB = Math.round(totalMem / 1024 / 1024);
248
248
  // Try to read agent and task counts from local store files
@@ -280,7 +280,7 @@ const monitorCommand = {
280
280
  system: {
281
281
  cpuLoadAvg1m: loadAvg[0] !== undefined ? parseFloat(loadAvg[0].toFixed(2)) : null,
282
282
  cpuLoadAvg5m: loadAvg[1] !== undefined ? parseFloat(loadAvg[1].toFixed(2)) : null,
283
- cpuCount: os.cpus().length,
283
+ cpuCount: cpus().length,
284
284
  memoryUsedMB: usedMemMB,
285
285
  memoryTotalMB: totalMemMB,
286
286
  processRssMB: Math.round(memUsage.rss / 1024 / 1024),
@@ -607,7 +607,6 @@ const logsCommand = {
607
607
  const minLevelIdx = levels.indexOf(level);
608
608
  if (existsSync(logsDir)) {
609
609
  try {
610
- const { readdirSync } = await import('node:fs');
611
610
  const logFiles = readdirSync(logsDir)
612
611
  .filter(f => f.endsWith('.log'))
613
612
  .filter(f => source === 'all' || f.includes(source));
@@ -21,7 +21,9 @@ import { output } from '../output.js';
21
21
  const DEFAULT_MANIFEST_URL = 'https://raw.githubusercontent.com/ruvnet/ruflo/{branch}/verification.md.json';
22
22
  async function fetchWitness(branch) {
23
23
  const url = DEFAULT_MANIFEST_URL.replace('{branch}', branch);
24
- const res = await fetch(url);
24
+ // audit_1776853149979: bare fetch had no timeout — a hung GitHub CDN would
25
+ // pin the verify command indefinitely. 30s is generous for a sub-MB JSON.
26
+ const res = await fetch(url, { signal: AbortSignal.timeout(30000) });
25
27
  if (!res.ok) {
26
28
  throw new Error(`Failed to fetch manifest from ${url}: ${res.status} ${res.statusText}`);
27
29
  }
@@ -48,12 +50,13 @@ function repoPathToInstalledPath(repoPath) {
48
50
  if (match) {
49
51
  const pkg = match[1];
50
52
  const rest = match[2];
51
- // Try several anchors: cwd/node_modules, the dirname of this script's package
52
53
  const candidates = [];
54
+ // 1. cwd/node_modules/<pkg>/<rest> (typical end-user install)
53
55
  candidates.push(join(process.cwd(), 'node_modules', pkg, rest));
56
+ // 2. Walk up from this script looking for node_modules/<pkg>/<rest>
57
+ // Covers cases where verify runs from inside a nested module.
54
58
  try {
55
59
  const __filename = fileURLToPath(import.meta.url);
56
- // Walk up looking for node_modules
57
60
  let dir = dirname(__filename);
58
61
  for (let i = 0; i < 10; i++) {
59
62
  candidates.push(join(dir, 'node_modules', pkg, rest));
@@ -64,6 +67,24 @@ function repoPathToInstalledPath(repoPath) {
64
67
  }
65
68
  }
66
69
  catch { /* ignore */ }
70
+ // 3. Source-tree resolution: when verify runs against a checked-out
71
+ // repo (the developer's working copy), packages live at
72
+ // `<repoRoot>/v3/<pkg>/<rest>` rather than under node_modules.
73
+ // Walk up looking for the literal repo-relative path so the verify
74
+ // command works for maintainers running it from the repo itself.
75
+ try {
76
+ const __filename = fileURLToPath(import.meta.url);
77
+ let dir = dirname(__filename);
78
+ for (let i = 0; i < 10; i++) {
79
+ candidates.push(join(dir, repoPath));
80
+ const parent = dirname(dir);
81
+ if (parent === dir)
82
+ break;
83
+ dir = parent;
84
+ }
85
+ }
86
+ catch { /* ignore */ }
87
+ candidates.push(join(process.cwd(), repoPath));
67
88
  for (const c of candidates) {
68
89
  if (existsSync(c))
69
90
  return c;
@@ -0,0 +1,94 @@
1
+ /**
2
+ * Encryption-at-rest vault primitives (ADR-096 Phase 1).
3
+ *
4
+ * Goal: provide deterministic encrypt/decrypt of arbitrary Buffers with a
5
+ * symmetric key, using a magic-byte format so readers of older plaintext
6
+ * stores can detect-then-pass-through during the migration window.
7
+ *
8
+ * Phase 1 deliberately ships only the cipher primitives + the env-var key
9
+ * source. Keychain (keytar) and interactive passphrase resolution land in
10
+ * a follow-up iteration so the blast radius of this commit is limited to
11
+ * a single self-contained module with no native dependencies.
12
+ *
13
+ * Wire format (output of encryptBuffer):
14
+ *
15
+ * +---------+-----------+----------------+--------+
16
+ * | magic 4 | iv 12 | ciphertext N | tag 16 |
17
+ * +---------+-----------+----------------+--------+
18
+ * "RFE1" random AES-256-GCM GCM
19
+ *
20
+ * The magic distinguishes encrypted blobs from plaintext during the
21
+ * incremental migration: readers call isEncryptedBlob() and either
22
+ * decryptBuffer() or treat the bytes as plaintext, so existing
23
+ * .claude-flow/sessions/*.json files keep working unchanged.
24
+ */
25
+ /** ASCII "RFE1" — Ruflo File Encrypted v1. 4 bytes. */
26
+ export declare const MAGIC: Buffer<ArrayBuffer>;
27
+ /**
28
+ * True when at-rest encryption should be applied to writes.
29
+ *
30
+ * Truthy values: "1", "true", "yes", "on" (case-insensitive). Anything else
31
+ * — including unset — keeps the legacy plaintext path. This is the gate
32
+ * that lets the 1865-test baseline keep passing unchanged while users opt
33
+ * into encryption.
34
+ */
35
+ export declare function isEncryptionEnabled(): boolean;
36
+ /**
37
+ * Resolve a 32-byte encryption key from CLAUDE_FLOW_ENCRYPTION_KEY.
38
+ *
39
+ * Phase 1 supports only the env-var source; keychain and passphrase
40
+ * resolution are deferred to a follow-up iteration (see ADR-096). When
41
+ * encryption is enabled but no key resolves, this throws with a clear
42
+ * message rather than silently falling back to plaintext (fail-closed).
43
+ *
44
+ * Accepted encodings (auto-detected by length):
45
+ * - 64-char hex (32 bytes)
46
+ * - 44-char base64 (32 bytes + padding)
47
+ * - exactly 32 raw bytes (rare; for callers that pre-decode)
48
+ *
49
+ * Anything else is rejected — we'd rather fail loudly than encrypt with a
50
+ * truncated key.
51
+ */
52
+ export declare function getKey(): Buffer;
53
+ /**
54
+ * Decode a key string. Exposed for testing and for the future passphrase
55
+ * resolver, which will scrypt-derive a Buffer and hand it back through here
56
+ * to share the same length-check.
57
+ */
58
+ export declare function decodeKey(raw: string): Buffer;
59
+ /**
60
+ * Encrypt a plaintext Buffer with AES-256-GCM. Returns the wire-format
61
+ * blob: magic(4) || iv(12) || ciphertext(N) || tag(16).
62
+ *
63
+ * The IV is freshly randomized per call. Reusing a (key, iv) pair under
64
+ * GCM is catastrophic — every call MUST produce a different IV. Node's
65
+ * randomBytes is csprng-backed so this is automatic; the function takes
66
+ * no IV input deliberately.
67
+ */
68
+ export declare function encryptBuffer(plaintext: Buffer, key: Buffer): Buffer;
69
+ /**
70
+ * Decrypt a wire-format blob. Verifies the magic byte (sanity), parses
71
+ * iv + ciphertext + tag, runs AES-256-GCM decrypt, and lets the GCM
72
+ * auth tag fail loudly on tamper (Node throws "Unsupported state or
73
+ * unable to authenticate data" — we let that propagate).
74
+ *
75
+ * Pre-condition: caller has already determined this is an encrypted
76
+ * blob via isEncryptedBlob(). decryptBuffer throws on bad magic so a
77
+ * mistaken plaintext blob still fails loudly rather than producing
78
+ * garbage.
79
+ */
80
+ export declare function decryptBuffer(blob: Buffer, key: Buffer): Buffer;
81
+ /**
82
+ * Magic-byte sniff. True iff the blob starts with the RFE1 magic AND is
83
+ * long enough to be a valid encrypted blob. Used by readers during the
84
+ * incremental migration: legacy plaintext files return false and flow
85
+ * through the existing read path unchanged.
86
+ *
87
+ * Note: this is a heuristic. A plaintext file that happens to start with
88
+ * "RFE1" would be misdetected — we accept that vanishingly small risk
89
+ * because (a) the four bytes 0x52,0x46,0x45,0x31 are an unusual prefix
90
+ * for JSON (`{`, `[`) or SQLite (`SQLite format 3`), and (b) decryption
91
+ * will then fail with a clear error rather than silently corrupt.
92
+ */
93
+ export declare function isEncryptedBlob(blob: Buffer): boolean;
94
+ //# sourceMappingURL=vault.d.ts.map