@claude-flow/cli 3.64.0 → 3.65.1

package/dist/src/init/risky-settings-gate.js

@@ -0,0 +1,130 @@
+/**
+ * ADR-509 §2.3: the stop `ruflo init` / `ruflo init upgrade --settings` makes
+ * before carrying a project settings file's auto-approve keys forward.
+ *
+ * The check runs BEFORE anything is written, so a stop leaves the project as
+ * it was. `keep` proceeds (the keys are still reported); `drop` proceeds and
+ * the merged file is written without them.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { isRufloHelperCommand } from './helper-commands.js';
+import { CRITICAL_HELPERS } from './helper-refresh.js';
+import { HELPERS_MANIFEST_FILE, sha256Hex, verifyHelpersManifest } from './helper-signing.js';
+import { dropAutoApproveKeys, formatRiskFindingsAsWarnings, scanProjectAutoApproveKeys, } from './settings-risk-scanner.js';
+export function scanAutoApprove(settings) {
+    return scanProjectAutoApproveKeys(settings, isRufloHelperCommand);
+}
+/** Reads a settings file and judges it; null when the file is absent, unreadable or not a JSON object. */
+export function checkRiskySettings(settingsPath, mode = 'stop') {
+    if (!fs.existsSync(settingsPath))
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+        return null;
+    const findings = scanAutoApprove(parsed);
+    if (findings.length === 0)
+        return null;
+    return { mode, findings, lines: formatRiskFindingsAsWarnings(findings), stop: mode === 'stop' };
+}
+/**
+ * ADR-509 §2.3: the helpers ruflo's hooks launch, as the PROJECT ships them.
+ * `init` keeps an existing `.claude/helpers/<name>` unless --force, and the
+ * project-scope hook commands prefer the project's copy, so a repository that
+ * ships its own hook-handler.cjs runs it under an exact ruflo hook command. A
+ * helper is trusted when its bytes are the copy this ruflo ships, or its
+ * SHA-256 is in a helpers manifest signed with ruflo's key (this ruflo's, or
+ * the project's own, which an older signed release left). Anything else is a
+ * finding. A `.LOCKED` helpers dir (deliberate local edits) is skipped, and with
+ * no ground truth at all this fails open. `pubkeyPem` is injectable for tests.
+ */
+export function untrustedProjectHelpers(targetDir, sourceHelpersDir, pubkeyPem) {
+    const helpersDir = path.join(targetDir, '.claude', 'helpers');
+    // .LOCKED is the sanctioned marker for deliberately edited helpers (helper-refresh honours it too).
+    if (fs.existsSync(path.join(helpersDir, '.LOCKED')))
+        return [];
+    const signed = (dir) => {
+        if (!dir)
+            return null;
+        try {
+            return verifyHelpersManifest(fs.readFileSync(path.join(dir, HELPERS_MANIFEST_FILE), 'utf-8'), pubkeyPem);
+        }
+        catch {
+            return null;
+        }
+    };
+    const manifests = [signed(sourceHelpersDir), signed(helpersDir)].filter((m) => m !== null);
+    // No ground truth at all (no shipped copy, no signed manifest): fail open, as
+    // helper-integrity does, rather than flag every install.
+    if (!sourceHelpersDir && manifests.length === 0)
+        return [];
+    const out = [];
+    for (const name of CRITICAL_HELPERS) {
+        const file = path.join(helpersDir, name);
+        let bytes;
+        try {
+            if (!fs.lstatSync(file).isFile())
+                throw new Error('not a regular file');
+            bytes = fs.readFileSync(file);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                continue;
+            out.push({ target: { kind: 'helper', name }, location: `.claude/helpers/${name}`, snippet: '(unreadable or not a regular file)', reason: "is not ruflo's signed helper; ruflo's hooks would run it" });
+            continue;
+        }
+        if (sourceHelpersDir) {
+            try {
+                if (bytes.equals(fs.readFileSync(path.join(sourceHelpersDir, name))))
+                    continue;
+            }
+            catch {
+                // not shipped by this ruflo: fall through to the signed manifests
+            }
+        }
+        const hash = sha256Hex(bytes);
+        if (manifests.some((m) => m.files[name] === hash))
+            continue;
+        out.push({
+            target: { kind: 'helper', name },
+            location: `.claude/helpers/${name}`,
+            snippet: `sha256 ${hash.slice(0, 16)}…`,
+            reason: "differs from ruflo's signed helper; init keeps it and ruflo's hooks would run it",
+        });
+    }
+    return out;
+}
+/**
+ * The init gate: the settings file's auto-approve keys plus the project's
+ * untrusted helpers. Null when there is nothing to report.
+ */
+export function checkInitTrust(targetDir, mode, sourceHelpersDir) {
+    const settings = checkRiskySettings(path.join(targetDir, '.claude', 'settings.json'), mode);
+    const helpers = untrustedProjectHelpers(targetDir, sourceHelpersDir);
+    const findings = [...(settings?.findings ?? []), ...helpers];
+    if (findings.length === 0)
+        return null;
+    return { mode, findings, lines: formatRiskFindingsAsWarnings(findings), stop: mode === 'stop' };
+}
+/** `drop`: the settings without the auto-approve keys; otherwise the settings unchanged. */
+export function applyRiskyMode(settings, mode) {
+    if (mode !== 'drop')
+        return { settings, dropped: 0 };
+    const findings = scanAutoApprove(settings);
+    return findings.length ? { settings: dropAutoApproveKeys(settings, findings), dropped: findings.length } : { settings, dropped: 0 };
+}
+/** Reads `--keep-risky-settings` / `--drop-risky-settings` (camel or kebab); both at once is an error. */
+export function riskyModeFromFlags(flags) {
+    const keep = flags.keepRiskySettings === true || flags['keep-risky-settings'] === true;
+    const drop = flags.dropRiskySettings === true || flags['drop-risky-settings'] === true;
+    if (keep && drop)
+        return { error: '--keep-risky-settings and --drop-risky-settings cannot be used together' };
+    return keep ? 'keep' : drop ? 'drop' : 'stop';
+}
+//# sourceMappingURL=risky-settings-gate.js.map

package/dist/src/init/settings-risk-scanner.d.ts

@@ -44,4 +44,39 @@ export declare function scanAllowRuleForRisk(rule: string): string[];
 export declare function scanSettingsForRisk(settings: Record<string, unknown>): SettingsRiskFinding[];
 /** Formats findings as short, human-readable CLI warning lines. */
 export declare function formatRiskFindingsAsWarnings(findings: SettingsRiskFinding[]): string[];
+/** What a finding points at, precisely enough for dropAutoApproveKeys to remove only that. */
+export type AutoApproveTarget = {
+    kind: 'enableAllProjectMcpServers';
+} | {
+    kind: 'enabledMcpjsonServers';
+} | {
+    kind: 'defaultMode';
+} | {
+    kind: 'allow';
+    index: number;
+} | {
+    kind: 'hook';
+    event: string;
+    group: number;
+    hook: number;
+}
+/** A project `.claude/helpers/<name>` that is not ruflo's signed copy (init keeps it without --force). */
+ | {
+    kind: 'helper';
+    name: string;
+};
+export interface AutoApproveFinding extends SettingsRiskFinding {
+    target: AutoApproveTarget;
+}
+/**
+ * The auto-approve keys of a PROJECT settings file (`.claude/settings.json` or
+ * `.claude/settings.local.json`). `isRufloHook` decides which hook commands are
+ * ruflo's own helpers (injected so this module stays dependency-free).
+ */
+export declare function scanProjectAutoApproveKeys(settings: Record<string, unknown>, isRufloHook: (command: string) => boolean): AutoApproveFinding[];
+/** A deep copy of `settings` without the keys/entries the findings point at. Never mutates its input. */
+export declare function dropAutoApproveKeys(settings: Record<string, unknown>, findings: readonly AutoApproveFinding[]): Record<string, unknown>;
+/** What `init` does when the existing settings carry auto-approve keys. */
+export type RiskySettingsMode = 'stop' | 'keep' | 'drop';
+export declare const RISKY_SETTINGS_HINT = "Re-run with --drop-risky-settings to write the merged settings without these keys (and replace any flagged helper with ruflo's copy), or --keep-risky-settings to keep them.";
 //# sourceMappingURL=settings-risk-scanner.d.ts.map

package/dist/src/init/settings-risk-scanner.js

@@ -177,4 +177,89 @@ export function scanSettingsForRisk(settings) {
 export function formatRiskFindingsAsWarnings(findings) {
     return findings.map((f) => `${f.location}: ${f.reason} — "${f.snippet}"`);
 }
+const isRecord = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+/** A bare `Bash`, `Bash(*)`, `Bash(*:*)` or a `*` wildcard pre-approves every command. */
+function isBlanketAllow(rule) {
+    const t = rule.trim();
+    return t === '*' || /^Bash$/i.test(t) || /^Bash\(\s*\*\s*(:\s*\*\s*)?\)$/i.test(t) || /^\*\s*\(.*\)$/.test(t);
+}
+/**
+ * The auto-approve keys of a PROJECT settings file (`.claude/settings.json` or
+ * `.claude/settings.local.json`). `isRufloHook` decides which hook commands are
+ * ruflo's own helpers (injected so this module stays dependency-free).
+ */
+export function scanProjectAutoApproveKeys(settings, isRufloHook) {
+    const out = [];
+    if (settings.enableAllProjectMcpServers === true) {
+        out.push({ target: { kind: 'enableAllProjectMcpServers' }, location: 'enableAllProjectMcpServers', snippet: 'true', reason: 'starts every .mcp.json server in the project without asking' });
+    }
+    const enabled = settings.enabledMcpjsonServers;
+    if (Array.isArray(enabled) && enabled.length > 0) {
+        out.push({ target: { kind: 'enabledMcpjsonServers' }, location: 'enabledMcpjsonServers', snippet: buildSnippet(enabled.map(String).join(', ')), reason: 'pre-approves .mcp.json servers before the trust dialog' });
+    }
+    const permissions = isRecord(settings.permissions) ? settings.permissions : undefined;
+    if (permissions?.defaultMode === 'bypassPermissions') {
+        out.push({ target: { kind: 'defaultMode' }, location: 'permissions.defaultMode', snippet: 'bypassPermissions', reason: 'turns off every permission prompt' });
+    }
+    if (Array.isArray(permissions?.allow)) {
+        permissions.allow.forEach((rule, index) => {
+            if (typeof rule === 'string' && isBlanketAllow(rule)) {
+                out.push({ target: { kind: 'allow', index }, location: `permissions.allow[${index}]`, snippet: buildSnippet(rule), reason: 'pre-approves every command (bare Bash or * wildcard)' });
+            }
+        });
+    }
+    const hooks = isRecord(settings.hooks) ? settings.hooks : undefined;
+    for (const [event, groups] of Object.entries(hooks ?? {})) {
+        if (!Array.isArray(groups))
+            continue;
+        groups.forEach((g, group) => {
+            const list = isRecord(g) && Array.isArray(g.hooks) ? g.hooks : [];
+            list.forEach((h, hook) => {
+                if (!isRecord(h) || typeof h.command !== 'string' || isRufloHook(h.command))
+                    return;
+                out.push({ target: { kind: 'hook', event, group, hook }, location: `hooks.${event}[${group}].hooks[${hook}]`, snippet: buildSnippet(h.command), reason: 'runs a command that is not a ruflo helper' });
+            });
+        });
+    }
+    return out;
+}
+/** A deep copy of `settings` without the keys/entries the findings point at. Never mutates its input. */
+export function dropAutoApproveKeys(settings, findings) {
+    const next = JSON.parse(JSON.stringify(settings));
+    const perms = isRecord(next.permissions) ? next.permissions : undefined;
+    const allowDrop = new Set();
+    const hookDrop = new Set();
+    for (const { target: t } of findings) {
+        if (t.kind === 'enableAllProjectMcpServers')
+            delete next.enableAllProjectMcpServers;
+        else if (t.kind === 'enabledMcpjsonServers')
+            delete next.enabledMcpjsonServers;
+        else if (t.kind === 'defaultMode' && perms)
+            delete perms.defaultMode;
+        else if (t.kind === 'allow')
+            allowDrop.add(t.index);
+        else if (t.kind === 'hook')
+            hookDrop.add(`${t.event}\u0000${t.group}\u0000${t.hook}`);
+    }
+    if (perms && Array.isArray(perms.allow))
+        perms.allow = perms.allow.filter((_, i) => !allowDrop.has(i));
+    if (isRecord(next.hooks) && hookDrop.size) {
+        for (const [event, groups] of Object.entries(next.hooks)) {
+            if (!Array.isArray(groups))
+                continue;
+            const kept = groups
+                .map((g, gi) => (isRecord(g) && Array.isArray(g.hooks) ? { ...g, hooks: g.hooks.filter((_, hi) => !hookDrop.has(`${event}\u0000${gi}\u0000${hi}`)) } : g))
+                .filter((g) => !(isRecord(g) && Array.isArray(g.hooks) && g.hooks.length === 0));
+            if (kept.length)
+                next.hooks[event] = kept;
+            else
+                delete next.hooks[event];
+        }
+        // No hooks left: drop the key, so init writes its own hooks as it does for a file without any.
+        if (Object.keys(next.hooks).length === 0)
+            delete next.hooks;
+    }
+    return next;
+}
+export const RISKY_SETTINGS_HINT = 'Re-run with --drop-risky-settings to write the merged settings without these keys (and replace any flagged helper with ruflo\'s copy), or --keep-risky-settings to keep them.';
 //# sourceMappingURL=settings-risk-scanner.js.map

package/dist/src/init/types.d.ts

@@ -296,6 +296,14 @@ export interface InitOptions {
      * GitHub contributor graph. Pass `--attribution` to opt in.
      */
     attribution?: boolean;
+    /**
+     * ADR-509 §2.3 — what to do when the existing project settings.json carries
+     * auto-approve keys (enableAllProjectMcpServers, enabledMcpjsonServers,
+     * bypassPermissions, blanket Bash allows, non-ruflo hooks): `stop`
+     * (default — nothing is written), `keep` (--keep-risky-settings) or `drop`
+     * (--drop-risky-settings).
+     */
+    riskySettings?: 'stop' | 'keep' | 'drop';
 }
 /**
  * Default init options - full V3 setup
@@ -334,5 +342,9 @@ export interface InitResult {
      * init — surfaced so a user can review before trusting it.
      */
     warnings?: string[];
+    /** ADR-509 §2.3 — auto-approve keys found in the existing project settings.json. */
+    riskySettings?: string[];
+    /** ADR-509 §2.3 — init stopped before writing anything because of riskySettings. */
+    stoppedOnRiskySettings?: boolean;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/src/mcp-tools/capability-brain.d.ts

@@ -97,7 +97,7 @@ export interface CapabilityBrain {
     };
 }
 /** Top-level commands from the CLI command loader. Kept as a checked manifest. */
-export declare const RUFLO_CLI_COMMANDS: readonly ["init", "start", "status", "task", "session", "agent", "swarm", "memory", "mcp", "config", "migrate", "hooks", "workflow", "hive-mind", "process", "daemon", "version", "neural", "security", "performance", "providers", "plugins", "deployment", "claims", "policy", "embeddings", "completions", "doctor", "verify", "analyze", "route", "progress", "issues", "update", "ruvector", "benchmark", "guidance", "appliance", "appliance-advanced", "transfer-store", "cleanup", "autopilot", "gaia-bench", "metaharness", "eject", "funnel", "settings", "auth", "proxy", "advisor", "spinner", "announcements", "tui", "harness"];
+export declare const RUFLO_CLI_COMMANDS: readonly ["init", "start", "status", "task", "session", "agent", "swarm", "memory", "mcp", "config", "migrate", "hooks", "workflow", "hive-mind", "process", "daemon", "version", "neural", "security", "performance", "providers", "plugins", "deployment", "claims", "policy", "embeddings", "completions", "doctor", "verify", "analyze", "route", "progress", "issues", "update", "ruvector", "benchmark", "guidance", "appliance", "appliance-advanced", "transfer-store", "cleanup", "autopilot", "gaia-bench", "metaharness", "eject", "funnel", "settings", "auth", "proxy", "advisor", "spinner", "cost", "announcements", "tui", "harness"];
 export interface ImplementationLoopStep {
     id: string;
     name: string;

package/dist/src/mcp-tools/capability-brain.js

@@ -15,7 +15,7 @@ export const RUFLO_CLI_COMMANDS = [
     'doctor', 'verify', 'analyze', 'route', 'progress', 'issues', 'update',
     'ruvector', 'benchmark', 'guidance', 'appliance', 'appliance-advanced',
     'transfer-store', 'cleanup', 'autopilot', 'gaia-bench', 'metaharness',
-    'eject', 'funnel', 'settings', 'auth', 'proxy', 'advisor', 'spinner',
+    'eject', 'funnel', 'settings', 'auth', 'proxy', 'advisor', 'spinner', 'cost',
     'announcements', 'tui', 'harness',
 ];
 export const IMPLEMENTATION_LOOP = [

package/dist/src/mcp-tools/hooks-tools.js

@@ -5482,7 +5482,8 @@ export const hooksVerifiedIngest = {
     handler: async (params) => {
         const { ingestVerifiedOutcomes } = await import('../memory/verified-outcomes.js');
         const sona = await getSONAOptimizer();
-        const result = await ingestVerifiedOutcomes({ dryRun: params.dryRun === true, force: params.force === true || params.dryRun === true, sona: sona });
+        // ADR-503 §2.3: only this explicit ingest may re-verify (run project code), and only when learningLoop.reverify is on.
+        const result = await ingestVerifiedOutcomes({ dryRun: params.dryRun === true, force: params.force === true || params.dryRun === true, sona: sona, allowReverify: true });
         return { success: true, ...result };
     },
 };

package/dist/src/mcp-tools/http-fetch-pinned.d.ts

@@ -0,0 +1,44 @@
+/**
+ * http_fetch's address checks and connection-pinned transport (ADR-164 §5.1.8).
+ *
+ * Checking the URL's hostname string is not enough: a public-looking name can resolve to
+ * loopback, RFC-1918 or cloud metadata (169.254.169.254), and `fetch()` resolves the name
+ * again on its own, so even a pre-resolution check can be rebound (TTL-0 DNS) between the
+ * check and the connect. Here the socket's DNS lookup *is* the check: `pinnedLookup`
+ * resolves the name, refuses it when any address is private, and hands the socket only the
+ * addresses it checked, so the connection cannot land anywhere else. IP-literal hosts never
+ * reach a lookup; `validateUrl` checks those by text, with the same `isPrivateOrLoopback`.
+ *
+ * @module @claude-flow/cli/mcp-tools/http-fetch-pinned
+ */
+import { type LookupFunction } from 'node:net';
+/** Raised when a hostname resolves to an address the allowlist refuses. */
+export declare class PrivateAddressError extends Error {
+    readonly code = "PRIVATE_ADDRESS";
+    constructor(host: string, address: string);
+}
+export declare const allowPrivateAddresses: () => boolean;
+/**
+ * Whether a host (an IP literal, bracketed or not, or `localhost`) is one http_fetch refuses
+ * by default. A name that is not an IP literal is `false` here: what it resolves to is
+ * checked at connect time by `pinnedLookup`.
+ */
+export declare function isPrivateOrLoopback(host: string): boolean;
+/**
+ * The socket's DNS lookup: resolve every address, refuse the host when any of them is
+ * private (unless opted in), and return only those checked addresses to the socket.
+ */
+export declare const pinnedLookup: LookupFunction;
+export interface PinnedInit {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+    signal: AbortSignal;
+}
+/**
+ * One HTTP(S) request whose connection goes only to an address `pinnedLookup` checked, with
+ * no redirect following and a fresh connection every time (no pooled socket from elsewhere).
+ * Returns a standard `Response` so the caller reads it as it would a `fetch()` result.
+ */
+export declare function pinnedRequest(url: string, init: PinnedInit): Promise<Response>;
+//# sourceMappingURL=http-fetch-pinned.d.ts.map

package/dist/src/mcp-tools/http-fetch-pinned.js

@@ -0,0 +1,148 @@
+/**
+ * http_fetch's address checks and connection-pinned transport (ADR-164 §5.1.8).
+ *
+ * Checking the URL's hostname string is not enough: a public-looking name can resolve to
+ * loopback, RFC-1918 or cloud metadata (169.254.169.254), and `fetch()` resolves the name
+ * again on its own, so even a pre-resolution check can be rebound (TTL-0 DNS) between the
+ * check and the connect. Here the socket's DNS lookup *is* the check: `pinnedLookup`
+ * resolves the name, refuses it when any address is private, and hands the socket only the
+ * addresses it checked, so the connection cannot land anywhere else. IP-literal hosts never
+ * reach a lookup; `validateUrl` checks those by text, with the same `isPrivateOrLoopback`.
+ *
+ * @module @claude-flow/cli/mcp-tools/http-fetch-pinned
+ */
+import { lookup as dnsLookup } from 'node:dns';
+import * as http from 'node:http';
+import * as https from 'node:https';
+import { isIP } from 'node:net';
+import { Readable } from 'node:stream';
+/** Raised when a hostname resolves to an address the allowlist refuses. */
+export class PrivateAddressError extends Error {
+    code = 'PRIVATE_ADDRESS';
+    constructor(host, address) {
+        super(`host ${host} resolves to ${address}, which is loopback/private/link-local; set CLAUDE_FLOW_HTTP_FETCH_ALLOW_PRIVATE=1 to override`);
+        this.name = 'PrivateAddressError';
+    }
+}
+export const allowPrivateAddresses = () => process.env.CLAUDE_FLOW_HTTP_FETCH_ALLOW_PRIVATE === '1';
+/** The 16-bit groups of an IPv6 address (brackets stripped), or null when it is not one. */
+function ipv6Groups(addr) {
+    if (isIP(addr) !== 6)
+        return null;
+    let text = addr.split('%')[0];
+    // A trailing dotted IPv4 (`::ffff:1.2.3.4`) is two groups.
+    const v4 = text.match(/(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+    if (v4) {
+        const [a, b, c, d] = v4.slice(1).map(Number);
+        text = `${text.slice(0, v4.index)}${((a << 8) | b).toString(16)}:${((c << 8) | d).toString(16)}`;
+    }
+    const [head, tail] = text.includes('::') ? text.split('::') : [text, undefined];
+    const parse = (s) => (s ? s.split(':').map((g) => parseInt(g, 16)) : []);
+    const h = parse(head);
+    const t = tail === undefined ? [] : parse(tail);
+    const groups = tail === undefined ? h : [...h, ...new Array(8 - h.length - t.length).fill(0), ...t];
+    return groups.length === 8 && groups.every((g) => Number.isInteger(g) && g >= 0 && g <= 0xffff) ? groups : null;
+}
+function privateIPv4(a, b) {
+    return a === 0 // 0.0.0.0/8 ("this" network)
+        || a === 127 // loopback
+        || a === 10 // RFC 1918
+        || (a === 172 && b >= 16 && b <= 31) // RFC 1918
+        || (a === 192 && b === 168) // RFC 1918
+        || (a === 169 && b === 254) // link-local, cloud metadata
+        || (a === 100 && b >= 64 && b <= 127) // CGNAT
+        || (a === 198 && (b === 18 || b === 19)) // benchmarking
+        || a >= 224; // multicast, reserved, broadcast
+}
+/**
+ * Whether a host (an IP literal, bracketed or not, or `localhost`) is one http_fetch refuses
+ * by default. A name that is not an IP literal is `false` here: what it resolves to is
+ * checked at connect time by `pinnedLookup`.
+ */
+export function isPrivateOrLoopback(host) {
+    const lower = host.toLowerCase();
+    if (lower === 'localhost' || lower === 'localhost.localdomain' || lower.endsWith('.localhost'))
+        return true;
+    const bare = lower.startsWith('[') && lower.endsWith(']') ? lower.slice(1, -1) : lower;
+    const v4 = bare.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+    if (v4)
+        return privateIPv4(Number(v4[1]), Number(v4[2]));
+    const g = ipv6Groups(bare);
+    if (!g)
+        return false;
+    const embedded = (hi) => privateIPv4(hi >> 8, hi & 0xff);
+    if (g.slice(0, 7).every((x) => x === 0) && g[7] <= 1)
+        return true; // :: and ::1
+    if (g.slice(0, 5).every((x) => x === 0) && g[5] === 0xffff)
+        return embedded(g[6]); // ::ffff:a.b.c.d (IPv4-mapped)
+    if (g.slice(0, 6).every((x) => x === 0))
+        return true; // ::a.b.c.d (deprecated IPv4-compatible)
+    if (g[0] === 0x64 && g[1] === 0xff9b)
+        return true; // 64:ff9b::/96 and /48 NAT64: may wrap any IPv4
+    if (g[0] === 0x2002)
+        return embedded(g[1]); // 6to4 carries an IPv4
+    if ((g[0] & 0xfe00) === 0xfc00)
+        return true; // fc00::/7 unique local
+    if ((g[0] & 0xffc0) === 0xfe80 || (g[0] & 0xffc0) === 0xfec0)
+        return true; // fe80::/10 link-local, fec0::/10 site-local
+    if ((g[0] & 0xff00) === 0xff00)
+        return true; // ff00::/8 multicast
+    return false;
+}
+/**
+ * The socket's DNS lookup: resolve every address, refuse the host when any of them is
+ * private (unless opted in), and return only those checked addresses to the socket.
+ */
+export const pinnedLookup = (hostname, options, callback) => {
+    dnsLookup(hostname, { ...options, all: true }, (err, addresses) => {
+        if (err)
+            return callback(err, []);
+        const list = addresses;
+        if (!allowPrivateAddresses()) {
+            const bad = list.find((a) => isPrivateOrLoopback(a.address));
+            if (bad || list.length === 0) {
+                return callback(new PrivateAddressError(hostname, bad?.address ?? 'no address'), []);
+            }
+        }
+        if (options.all)
+            return callback(null, list);
+        callback(null, list[0].address, list[0].family);
+    });
+};
+/** Statuses whose Response must not carry a body. */
+const NULL_BODY = new Set([101, 103, 204, 205, 304]);
+/**
+ * One HTTP(S) request whose connection goes only to an address `pinnedLookup` checked, with
+ * no redirect following and a fresh connection every time (no pooled socket from elsewhere).
+ * Returns a standard `Response` so the caller reads it as it would a `fetch()` result.
+ */
+export function pinnedRequest(url, init) {
+    const target = new URL(url);
+    const client = target.protocol === 'https:' ? https : http;
+    const headers = { accept: '*/*', ...init.headers };
+    if (init.body !== undefined && !Object.keys(headers).some((k) => k.toLowerCase() === 'content-length')) {
+        headers['content-length'] = String(Buffer.byteLength(init.body));
+    }
+    return new Promise((resolve, reject) => {
+        const req = client.request(target, { method: init.method, headers, lookup: pinnedLookup, agent: false, signal: init.signal }, (res) => {
+            const out = new Headers();
+            for (const [key, value] of Object.entries(res.headers)) {
+                for (const v of Array.isArray(value) ? value : value === undefined ? [] : [value])
+                    out.append(key, v);
+            }
+            const status = res.statusCode ?? 0;
+            if (status < 200 || status > 599) {
+                res.destroy();
+                reject(new Error(`unsupported HTTP status ${status}`));
+                return;
+            }
+            const body = NULL_BODY.has(status) || init.method === 'HEAD' ? null : Readable.toWeb(res);
+            if (body === null)
+                res.resume();
+            resolve(new Response(body, { status, statusText: res.statusMessage ?? '', headers: out }));
+        });
+        req.on('error', reject);
+        req.end(init.body);
+    });
+}
+//# sourceMappingURL=http-fetch-pinned.js.map

package/dist/src/mcp-tools/http-fetch-tools.d.ts

@@ -11,7 +11,10 @@
  * AbortController, response truncation, default User-Agent.
  *
  * Architectural constraints (load-bearing):
- *   - DEFAULT-REFUSES private addresses + loopback (CLAUDE_FLOW_HTTP_FETCH_ALLOW_PRIVATE=1 opt-in)
+ *   - DEFAULT-REFUSES private addresses + loopback (CLAUDE_FLOW_HTTP_FETCH_ALLOW_PRIVATE=1 opt-in):
+ *     IP literals by text here, and every resolved address of a hostname at connect time, on the
+ *     connection itself (http-fetch-pinned.ts), so DNS that points at, or rebinds to, a private
+ *     address is refused too
  *   - DEFAULT-REFUSES Authorization / Cookie / X-Auth-* (CLAUDE_FLOW_HTTP_FETCH_ALLOW_AUTH=1 opt-in)
  *   - hard timeout 30s default, 60s ceiling
  *   - response truncated to 256KB default, 1MB ceiling
@@ -20,6 +23,8 @@
  * @module @claude-flow/cli/mcp-tools/http-fetch
  */
 import type { MCPTool } from './types.js';
+import { type PinnedInit } from './http-fetch-pinned.js';
+export { isPrivateOrLoopback } from './http-fetch-pinned.js';
 export declare class HttpFetchValidationError extends Error {
     readonly code: string;
     constructor(message: string, code: string);
@@ -45,11 +50,15 @@ export interface HttpFetchResult {
     error?: string;
     errorCode?: string;
 }
+/** How one request is sent; tests replace it to script responses. The default pins each connection to checked addresses. */
+export type HttpFetchRequest = (url: string, init: PinnedInit) => Promise<Response>;
 /**
  * Pure execution path so tests can call it without going through the MCP
  * dispatcher. Returns a result object (does not throw on validation failure
  * — it returns success: false with an errorCode).
  */
-export declare function httpFetchExecute(input: Record<string, unknown>): Promise<HttpFetchResult>;
+export declare function httpFetchExecute(input: Record<string, unknown>, deps?: {
+    request?: HttpFetchRequest;
+}): Promise<HttpFetchResult>;
 export declare const httpFetchTools: MCPTool[];
 //# sourceMappingURL=http-fetch-tools.d.ts.map