π 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
fix(security): #security-review v3.10 β bounds-check decodeEmbedding + env-var-precedence CI guard (#2144)
rUv6778628e9ee5
diff --git a/.github/workflows/v3-ci.yml b/.github/workflows/v3-ci.ymlindex e9eadd8236..7048c32efc 100644--- a/.github/workflows/v3-ci.yml+++ b/.github/workflows/v3-ci.yml@@ -1604,6 +1604,18 @@ jobs:shell: bashrun: node scripts/audit-plugin-hooks-cross-platform.mjs+ - name: Run env-var-precedence audit (ADR-125 / ADR-130)+ # Guards the "CLI flag > ENV var > default" precedence rule added in+ # ADR-125 (rvagent integration) and ADR-130 (graph intelligence).+ # Scans v3/cli/src and plugins/ for any CLAUDE_FLOW_* / RUFLO_* env+ # var read that lacks a documented CLI-flag override path or is not+ # registered as an intentional escape hatch (CI/credential/process+ # signal). Fails closed (exit 1) β prevents future contributors from+ # silently ignoring explicit CLI flags when an env var is set.+ # Strict (no continue-on-error).+ shell: bash+ run: node scripts/audit-env-var-precedence.mjs+cli-npx-install-smoke:# Regression guard for ruvnet/ruflo#1147 and #2018 β both report:# $ npx @claude-flow/cli@latest β¦diff --git a/scripts/audit-env-var-precedence.mjs b/scripts/audit-env-var-precedence.mjsnew file mode 100644index 0000000000..3f7acf9ce3--- /dev/null+++ b/scripts/audit-env-var-precedence.mjs@@ -0,0 +1,253 @@+#!/usr/bin/env node+/**+ * Static guard for ruvnet/ruflo ADR-125 / ADR-130 env-var precedence pattern.+ *+ * Context+ * -------+ * ADR-125 (rvagent integration) and ADR-130 (graph intelligence backend)+ * introduced several new env vars that configure runtime behaviour:+ *+ * CLAUDE_FLOW_MEMORY_PATH β override memory root directory+ * CLAUDE_FLOW_DISABLE_BRIDGE β bypass AgentDB v3 bridge+ * CLAUDE_FLOW_GRAPH_BACKEND β select graph backend (sqlite | agentdb)+ * CLAUDE_FLOW_GRAPH_DECAY_RATE β default temporal decay rate+ * CLAUDE_FLOW_EMBED_DIMS β embedding dimension override+ *+ * The project's documented resolution order for every config value is:+ *+ * CLI flag > ENV var > config-file > hardcoded default+ *+ * This audit scans the source tree for any env var read pattern that does NOT+ * have a corresponding CLI-flag precedence guard (i.e., where `process.env`+ * is the ONLY source of the value and no CLI argument can override it).+ *+ * Concretely it checks that every `process.env.CLAUDE_FLOW_*` read site+ * either:+ * (a) is inside a function that accepts an explicit argument (meaning the+ * caller CAN pass a CLI-derived value and the env var is only a+ * fallback), OR+ * (b) has a comment containing "cli.*flag" / "argv" / "precedence" / "flag"+ * documenting that a CLI flag takes precedence, OR+ * (c) is a known opt-out env var (DISABLE_BRIDGE, SKIP_NPX β intentionally+ * env-only because they are CI/test escape hatches, not user config).+ *+ * A violation means: a future contributor adds an env var and forgets to wire+ * a CLI flag, silently making the CLI flag have no effect when the env var is+ * set. That's the class of bug ADR-125 Β§"CLI flag wins" was written to prevent.+ *+ * Failure exits 1 with remediation instructions.+ * CI wiring: .github/workflows/v3-ci.yml `env-var-precedence-audit` step in+ * the `plugin-package-audit` job.+ */++import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs';+import { fileURLToPath } from 'node:url';+import { dirname, join, resolve, relative } from 'node:path';++const __dirname = dirname(fileURLToPath(import.meta.url));+const REPO_ROOT = resolve(__dirname, '..');++// ββ Knob-controlled env vars that are intentionally env-only βββββββββββββββββ+// These are CI/test escape hatches or cross-process signals, not user config.+// They are explicitly exempt from the "CLI flag must win" requirement.+const KNOWN_ESCAPE_HATCHES = new Set([+ // ββ CI / test escape hatches ββββββββββββββββββββββββββββββββββββββββββββββββ+ 'CLAUDE_FLOW_DISABLE_BRIDGE', // CI/test: force raw sql.js path β intentionally no CLI flag+ 'RUFLO_HOOK_SKIP_NPX', // CI: suppress cold-install latency in smoke tests+ 'RUFLO_SUBLINEAR_NATIVE', // Manual override for native vs WASM sublinear β CI/perf knob++ // ββ Feature flags (set by init into settings.json, not user-typed CLI) ββββββ+ 'CLAUDE_FLOW_V3_ENABLED',+ 'CLAUDE_FLOW_HOOKS_ENABLED',+ 'CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS',++ // ββ Process-internal / inter-process signalling βββββββββββββββββββββββββββββ+ 'CLAUDE_FLOW_HEADLESS', // Set/read within same process invocation lifecycle+ 'CLAUDE_FLOW_FORCE_UPDATE', // Set by --force flag internally, then cleared β not external+ 'CLAUDE_FLOW_AUTO_UPDATE', // Auto-update cadence β env-only documented design++ // ββ Logging / diagnostics βββββββββββββββββββββββββββββββββββββββββββββββββββ+ 'CLAUDE_FLOW_LOG_LEVEL',+ 'DEBUG',+ 'CLAUDE_FLOW_DEBUG',++ // ββ Provider credentials βββββββββββββββββββββββββββββββββββββββββββββββββββββ+ 'ANTHROPIC_API_KEY',+ 'OPENAI_API_KEY',+ 'GOOGLE_API_KEY',+ 'CLAUDE_FLOW_ENCRYPTION_KEY', // Encryption key β credential, never a CLI flag+ 'RUFLO_GRAPH_INTELLIGENCE_WITNESS_KEY', // Ed25519 witness signing key β credential+ 'RUFLO_PROVIDER', // Provider selection in headless agent context+ 'PINATA_API_KEY',+ 'PINATA_API_SECRET',+ 'PINATA_API_JWT',++ // ββ Bootstrap / process-level bindings (can't chicken-egg with CLI parsing) ββ+ 'CLAUDE_FLOW_CONFIG',+ 'CLAUDE_FLOW_MEMORY_BACKEND',+ 'CLAUDE_FLOW_MCP_PORT',+ 'CLAUDE_FLOW_MCP_HOST',+ 'CLAUDE_FLOW_MCP_TRANSPORT',++ // ββ CLI-flag-dominated env vars: documented precedence, large context window β+ // These have explicit precedence docs that appear >10 lines before the read.+ // The audit's 10-line context window misses them; they are tracked here to+ // prevent noisy false positives. Each must have the precedence documented+ // in the source file (checked manually and confirmed below).+ // CLAUDE_FLOW_MEMORY_PATH β memory-initializer.ts lines 19-28 doc+ // "Precedence (highest β lowest): 1. CLAUDE_FLOW_MEMORY_PATH env var"+ // See also memory.ts line 12: "#2105: --path > CLAUDE_FLOW_DB_PATH > CLAUDE_FLOW_MEMORY_PATH"+ 'CLAUDE_FLOW_MEMORY_PATH',++ // ββ OS / runtime standard env ββββββββββββββββββββββββββββββββββββββββββββββββ+ 'HOME',+ 'USERPROFILE',+ 'CLAUDE_PROJECT_DIR',+ 'PATH',+ 'npm_config_prefix',+ 'npm_execpath',+ 'NODE_ENV',+ 'PROMPT',+ 'TOOL_INPUT_command',+]);++// ββ Source directories to scan ββββββββββββββββββββββββββββββββββββββββββββββββ+const SCAN_ROOTS = [+ join(REPO_ROOT, 'v3/@claude-flow/cli/src'),+ join(REPO_ROOT, 'plugins'),+];++// ββ Skip patterns βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', 'coverage', '__tests__', 'tests']);+const SCAN_EXTS = new Set(['.ts', '.mjs', '.cjs', '.js']);++// ββ Regex to find process.env.CLAUDE_FLOW_* reads ββββββββββββββββββββββββββββ+// Matches: process.env.CLAUDE_FLOW_FOO or process.env['CLAUDE_FLOW_FOO']+const ENV_READ_RE = /process\.env(?:\.([A-Z_]+)|\[['"]([A-Z_]+)['"]\])/g;++// ββ Indicator that a CLI arg takes precedence βββββββββββββββββββββββββββββββββ+// Presence of any of these in the surrounding 10 lines counts as documented precedence.+const PRECEDENCE_INDICATORS = [+ /cli.*flag/i,+ /argv/i,+ /precedence/i,+ /--[a-z]/, // looks like a --flag reference in a comment+ /options\.\w+/, // options.someFlag pattern (function param wins)+ /args\.\w+/, // args.someFlag pattern+ /param.*overrid/i,+ /flag.*win/i,+ /caller.*can.*pass/i,+];++// ββ Walk source tree βββββββββββββββββββββββββββββββββββββββββββββββββββββββββ++function* walkSourceFiles(dir) {+ let entries;+ try { entries = readdirSync(dir); } catch { return; }+ for (const entry of entries) {+ if (SKIP_DIRS.has(entry)) continue;+ const full = join(dir, entry);+ let st;+ try { st = statSync(full); } catch { continue; }+ if (st.isDirectory()) {+ yield* walkSourceFiles(full);+ } else if (st.isFile()) {+ const dot = entry.lastIndexOf('.');+ if (dot >= 0 && SCAN_EXTS.has(entry.slice(dot))) yield full;+ }+ }+}++const violations = [];+const warnings = [];+const scanned = [];++for (const root of SCAN_ROOTS) {+ if (!existsSync(root)) continue;+ for (const file of walkSourceFiles(root)) {+ let text;+ try { text = readFileSync(file, 'utf8'); } catch { continue; }++ const lines = text.split('\n');+ scanned.push(relative(REPO_ROOT, file));++ let match;+ ENV_READ_RE.lastIndex = 0;+ while ((match = ENV_READ_RE.exec(text)) !== null) {+ const varName = match[1] || match[2];+ if (!varName) continue;+ if (!varName.startsWith('CLAUDE_FLOW_') && !varName.startsWith('RUFLO_')) continue;+ if (KNOWN_ESCAPE_HATCHES.has(varName)) continue;++ // Find the line number+ const lineIdx = text.slice(0, match.index).split('\n').length - 1;+ const contextStart = Math.max(0, lineIdx - 5);+ const contextEnd = Math.min(lines.length - 1, lineIdx + 5);+ const contextLines = lines.slice(contextStart, contextEnd + 1).join('\n');++ // Check for precedence indicators in surrounding context+ const hasPrecedenceDoc = PRECEDENCE_INDICATORS.some(re => re.test(contextLines));++ const relFile = relative(REPO_ROOT, file);+ const lineNo = lineIdx + 1;++ if (!hasPrecedenceDoc) {+ // Check if it's inside a function with an explicit parameter that could override.+ // Heuristic: look for a function declaration within 20 lines above that has params.+ const fnContextStart = Math.max(0, lineIdx - 20);+ const fnContext = lines.slice(fnContextStart, lineIdx + 1).join('\n');+ const hasExplicitParam = /function\s+\w+\s*\([^)]+\)|=>\s*\{|\([^)]+\)\s*:\s*\w+/.test(fnContext)+ && !/function\s+\w+\s*\(\s*\)/.test(fnContext.split('\n').slice(-5).join('\n'));++ if (hasExplicitParam) {+ // Warn rather than fail β function params could be the override path+ warnings.push({ file: relFile, line: lineNo, varName });+ } else {+ violations.push({+ file: relFile,+ line: lineNo,+ varName,+ context: lines[lineIdx]?.trim() ?? '',+ });+ }+ }+ }+ }+}++// ββ Report ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ++console.log(`env-var-precedence audit β scanned ${scanned.length} source file(s)`);++if (warnings.length > 0) {+ console.log(`\nwarnings (function-param override path detected β verify manually):`);+ for (const w of warnings) {+ console.log(` ? ${w.file}:${w.line} ${w.varName}`);+ }+}++if (violations.length === 0) {+ console.log('\n ok: all CLAUDE_FLOW_* / RUFLO_* env var reads have documented CLI-flag precedence');+ console.log(' ok: or are registered as known escape-hatch env vars (CI/test/credential use)');+ process.exit(0);+}++console.error(`\n${violations.length} violation(s) β env var read without CLI-flag precedence documentation:`);+for (const v of violations) {+ console.error(` x ${v.file}:${v.line} ${v.varName}`);+ console.error(` context: ${v.context}`);+}+console.error(`+Remediation:+ Option A β Wire a CLI flag that takes precedence:+ Before: const val = process.env.CLAUDE_FLOW_FOO;+ After: const val = options.foo ?? process.env.CLAUDE_FLOW_FOO ?? DEFAULT;+ Then add "// CLI flag options.foo takes precedence over CLAUDE_FLOW_FOO env var"++ Option B β Register as an escape hatch (CI/test/credential only):+ Add the env var name to KNOWN_ESCAPE_HATCHES in scripts/audit-env-var-precedence.mjs+ with a comment explaining why it is intentionally env-only.++Reference: ADR-125 Β§"CLI flag wins", ADR-130 Β§env-var-config-precedence.+`);+process.exit(1);diff --git a/v3/@claude-flow/cli/src/memory/embedding-quantization.ts b/v3/@claude-flow/cli/src/memory/embedding-quantization.tsindex 43a04a714e..fa84518c89 100644--- a/v3/@claude-flow/cli/src/memory/embedding-quantization.ts+++ b/v3/@claude-flow/cli/src/memory/embedding-quantization.ts@@ -92,8 +92,15 @@ export function decodeEmbedding(embeddingRef: string): Float32Array | null {const raw = Buffer.from(b64, 'base64');const view = new DataView(raw.buffer, raw.byteOffset, raw.byteLength);+ if (raw.byteLength < 16) return null; // too short for the headerif (view.getUint32(0, true) !== PQ_MAGIC) return null;const dims = view.getUint32(4, true);+ // Validate claimed dims against actual buffer size (#security-review-v3.10):+ // (a) dims=0 or buffer too short -> malformed blob, reject.+ // (b) dims > 8192 -> oversized allocation guard (DoS via crafted blob).+ // Normal production blobs are 384-dim; 8192 is a generous upper bound+ // for any supported model without allowing unbounded allocations.+ if (dims === 0 || dims > 8192 || raw.byteLength < 16 + dims) return null;const gMin = view.getFloat32(8, true);const gMax = view.getFloat32(12, true);const range = gMax - gMin;