🌊 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
feat(doctor): report signed-helper integrity mismatches (#3565 follow-up)
ruvb72ca9f7d88a
diff --git a/v3/@claude-flow/cli/__tests__/doctor-helper-integrity-3565.test.ts b/v3/@claude-flow/cli/__tests__/doctor-helper-integrity-3565.test.tsnew file mode 100644index 0000000000..facca17c41--- /dev/null+++ b/v3/@claude-flow/cli/__tests__/doctor-helper-integrity-3565.test.ts@@ -0,0 +1,112 @@+/**+ * #3565: `ruflo doctor` reports signed critical helpers whose on-disk content+ * no longer matches the signed manifest. Uses a throwaway-keypair-signed+ * fixture (same approach as helper-refresh.test.ts) so the result does not+ * depend on the state of this repo's own signed manifest.+ */+import { describe, it, expect, afterEach } from 'vitest';+import { mkdtempSync, mkdirSync, writeFileSync } from 'node:fs';+import { join } from 'node:path';+import { tmpdir } from 'node:os';+import { generateKeyPairSync, sign as edSign } from 'node:crypto';++import { checkHelperIntegrity } from '../src/commands/doctor.js';+import { canonicalManifestBytes, sha256Hex } from '../src/init/helper-signing.js';++const GENUINE = 'intelligence.feedback(true); // genuine, signed content\n';++function makeSignedSource(content = GENUINE): { sourceDir: string; pubkeyPem: string } {+ const sourceDir = mkdtempSync(join(tmpdir(), 'doctor-helpers-source-'));+ writeFileSync(join(sourceDir, 'hook-handler.cjs'), content);+ const { publicKey, privateKey } = generateKeyPairSync('ed25519');+ const manifest = { version: '9.9.9', files: { 'hook-handler.cjs': sha256Hex(content) } };+ const signature = edSign(null, canonicalManifestBytes(manifest), privateKey).toString('base64');+ writeFileSync(join(sourceDir, 'helpers.manifest.json'), JSON.stringify({ manifest, signature, algorithm: 'ed25519' }));+ return { sourceDir, pubkeyPem: publicKey.export({ type: 'spki', format: 'pem' }).toString() };+}++function makeInstall(hookHandler: string): { cwd: string; helpersDir: string; homeDir: string } {+ const cwd = mkdtempSync(join(tmpdir(), 'doctor-helpers-project-'));+ const helpersDir = join(cwd, '.claude', 'helpers');+ mkdirSync(helpersDir, { recursive: true });+ writeFileSync(join(helpersDir, 'hook-handler.cjs'), hookHandler);+ const homeDir = mkdtempSync(join(tmpdir(), 'doctor-helpers-home-')); // empty: no global helpers+ return { cwd, helpersDir, homeDir };+}++describe('doctor checkHelperIntegrity (#3565)', () => {+ const savedEnv = process.env.RUFLO_HELPERS_LOCKED;+ afterEach(() => {+ if (savedEnv === undefined) delete process.env.RUFLO_HELPERS_LOCKED;+ else process.env.RUFLO_HELPERS_LOCKED = savedEnv;+ });++ it('passes when installed helpers match the signed manifest', async () => {+ const { cwd, homeDir } = makeInstall(GENUINE);+ const { sourceDir, pubkeyPem } = makeSignedSource();+ const r = await checkHelperIntegrity({ cwd, homeDir, sourceDirOverride: sourceDir, pubkeyPemOverride: pubkeyPem });+ expect(r.status).toBe('pass');+ });++ it('fails and names the file when an installed helper was tampered with', async () => {+ const { cwd, helpersDir, homeDir } = makeInstall('require("child_process").execSync("true"); // TAMPERED\n');+ const { sourceDir, pubkeyPem } = makeSignedSource();+ const r = await checkHelperIntegrity({ cwd, homeDir, sourceDirOverride: sourceDir, pubkeyPemOverride: pubkeyPem });+ expect(r.status).toBe('fail');+ expect(r.message).toContain(helpersDir);+ expect(r.message).toContain('hook-handler.cjs');+ });++ it('checks the global ~/.claude/helpers dir too', async () => {+ const { cwd, homeDir } = makeInstall(GENUINE);+ const globalDir = join(homeDir, '.claude', 'helpers');+ mkdirSync(globalDir, { recursive: true });+ writeFileSync(join(globalDir, 'hook-handler.cjs'), 'TAMPERED GLOBAL\n');+ const { sourceDir, pubkeyPem } = makeSignedSource();+ const r = await checkHelperIntegrity({ cwd, homeDir, sourceDirOverride: sourceDir, pubkeyPemOverride: pubkeyPem });+ expect(r.status).toBe('fail');+ expect(r.message).toContain(globalDir);+ });++ it('downgrades a mismatch to warn when .LOCKED marks a deliberate local edit', async () => {+ const { cwd, helpersDir, homeDir } = makeInstall('HAND-EDITED\n');+ writeFileSync(join(helpersDir, '.LOCKED'), '');+ const { sourceDir, pubkeyPem } = makeSignedSource();+ const r = await checkHelperIntegrity({ cwd, homeDir, sourceDirOverride: sourceDir, pubkeyPemOverride: pubkeyPem });+ expect(r.status).toBe('warn');+ expect(r.message).toContain('hook-handler.cjs');+ });++ it('treats RUFLO_HELPERS_LOCKED like .LOCKED', async () => {+ process.env.RUFLO_HELPERS_LOCKED = '1';+ const { cwd, homeDir } = makeInstall('HAND-EDITED\n');+ const { sourceDir, pubkeyPem } = makeSignedSource();+ const r = await checkHelperIntegrity({ cwd, homeDir, sourceDirOverride: sourceDir, pubkeyPemOverride: pubkeyPem });+ expect(r.status).toBe('warn');+ });++ it('fails closed when the package manifest signature does not verify', async () => {+ const { cwd, homeDir } = makeInstall(GENUINE);+ const { sourceDir } = makeSignedSource();+ const { publicKey: wrongKey } = generateKeyPairSync('ed25519');+ const r = await checkHelperIntegrity({+ cwd, homeDir, sourceDirOverride: sourceDir,+ pubkeyPemOverride: wrongKey.export({ type: 'spki', format: 'pem' }).toString(),+ });+ expect(r.status).toBe('fail');+ expect(r.message).toMatch(/signature invalid|missing/);+ });++ it('warns instead of claiming a pass when the package helper source cannot be found', async () => {+ const { cwd, homeDir } = makeInstall(GENUINE);+ const r = await checkHelperIntegrity({ cwd, homeDir, sourceDirOverride: null });+ expect(r.status).toBe('warn');+ });++ it('passes with nothing to verify outside a ruflo project', async () => {+ const cwd = mkdtempSync(join(tmpdir(), 'doctor-helpers-empty-'));+ const homeDir = mkdtempSync(join(tmpdir(), 'doctor-helpers-home-'));+ const r = await checkHelperIntegrity({ cwd, homeDir, sourceDirOverride: null });+ expect(r.status).toBe('pass');+ });+});diff --git a/v3/@claude-flow/cli/src/commands/doctor.ts b/v3/@claude-flow/cli/src/commands/doctor.tsindex b9bb21cf19..b65e54f686 100644--- a/v3/@claude-flow/cli/src/commands/doctor.ts+++ b/v3/@claude-flow/cli/src/commands/doctor.ts@@ -260,6 +260,75 @@ async function checkStaleSettingsNpx(): Promise<HealthCheck> {};}+/**+ * #3565: report signed critical helpers whose on-disk content no longer+ * matches the signed manifest. CLI startup heals such files, so this matters+ * for the paths startup does not heal: `.LOCKED` or `RUFLO_HELPERS_LOCKED`+ * (auto-restore skipped by design), an unverifiable package manifest, and an+ * unresolvable package source.+ */+export async function checkHelperIntegrity(opts: {+ cwd?: string;+ homeDir?: string;+ sourceDirOverride?: string | null;+ pubkeyPemOverride?: string;+} = {}): Promise<HealthCheck> {+ const name = 'Helper Integrity (#3565)';+ const { verifyInstalledCriticalHelpers } = await import('../init/helper-integrity.js');+ const { CRITICAL_HELPERS, findPackageHelpersDir } = await import('../init/helper-refresh.js');+ const envLocked = /^(1|true|on|yes)$/i.test(String(process.env.RUFLO_HELPERS_LOCKED || ''));+ const home = opts.homeDir ?? process.env.HOME ?? '';+ const dirs = [+ join(opts.cwd ?? process.cwd(), '.claude', 'helpers'),+ ...(home ? [join(home, '.claude', 'helpers')] : []),+ ].filter((d, i, a) => a.indexOf(d) === i && existsSync(join(d, 'hook-handler.cjs')));+ if (dirs.length === 0) {+ return { name, status: 'pass', message: 'no installed ruflo helpers to verify' };+ }++ const source = opts.sourceDirOverride === undefined ? findPackageHelpersDir() : opts.sourceDirOverride;+ if (!source) {+ return {+ name, status: 'warn',+ message: 'cannot verify installed helpers: the package helper source was not found',+ fix: 'Reinstall @claude-flow/cli',+ };+ }++ const tamperedLines: string[] = [];+ const lockedLines: string[] = [];+ for (const dir of dirs) {+ const r = verifyInstalledCriticalHelpers(dir, source, CRITICAL_HELPERS, opts.pubkeyPemOverride);+ if (r.blocked) {+ return {+ name, status: 'fail',+ message: `cannot verify installed helpers: ${r.blocked}`,+ fix: 'Reinstall @claude-flow/cli from a trusted source',+ };+ }+ if (r.tampered.length === 0) continue;+ const line = `${dir}: ${r.tampered.join(', ')}`;+ if (envLocked || existsSync(join(dir, '.LOCKED'))) lockedLines.push(line);+ else tamperedLines.push(line);+ }++ if (tamperedLines.length > 0) {+ return {+ name, status: 'fail',+ message: `critical helpers do not match the signed manifest — ${tamperedLines.join('; ')}`,+ fix: 'Run any ruflo command to restore verified copies (startup heals them), or `npx ruflo init --force`; then find out what modified them',+ };+ }+ if (lockedLines.length > 0) {+ return {+ name, status: 'warn',+ message: `locally modified helpers (auto-restore disabled by .LOCKED / RUFLO_HELPERS_LOCKED) — ${lockedLines.join('; ')}`,+ fix: 'Expected if you edit helpers deliberately; otherwise remove .LOCKED and run any ruflo command to restore them',+ };+ }+ return { name, status: 'pass', message: `${dirs.length} helper dir(s) match the signed manifest` };+}+async function checkDaemonStatus(): Promise<HealthCheck> {try {const pidFile = '.claude-flow/daemon.pid';@@ -2631,6 +2700,7 @@ export const doctorCommand: Command = {checkGitRepo,checkConfigFile,checkStaleSettingsNpx, // #2448/#2677 — runaway `npx @latest` in settings+ () => checkHelperIntegrity(), // #3565 — installed signed helpers vs manifestcheckDaemonStatus,checkMemoryDatabase,checkMemoryStructuralIntegrity, // #2737 — bounded, native quick_check on every default run@@ -2672,6 +2742,7 @@ export const doctorCommand: Command = {'browser': checkAgentBrowserVersion,'config': checkConfigFile,'stale-settings': checkStaleSettingsNpx, // #2448+ 'helpers': () => checkHelperIntegrity(), // #3565'daemon': checkDaemonStatus,'memory': [checkMemoryDatabase, // existing: exists + statable (unchanged)diff --git a/v3/@claude-flow/cli/src/init/helper-refresh.ts b/v3/@claude-flow/cli/src/init/helper-refresh.tsindex 94fc7ad53d..c73a2fcfa0 100644--- a/v3/@claude-flow/cli/src/init/helper-refresh.ts+++ b/v3/@claude-flow/cli/src/init/helper-refresh.ts@@ -236,7 +236,7 @@ export function getInstalledCliVersion(): string {}/** Locate the in-package `.claude/helpers` dir (the copy source). Null if not found. */-function findPackageHelpersDir(): string | null {+export function findPackageHelpersDir(): string | null {const candidates: string[] = [];try {const esmRequire = createRequire(import.meta.url);