Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 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

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.ts
new file mode 100644
index 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.ts
index 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 manifest
checkDaemonStatus,
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.ts
index 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);