@cruxy/cli 0.26.0 → 0.28.0

package/dist/mcp/service.d.ts

@@ -1,4 +1,5 @@
 import type { CruxyConfig, McpServerConfig } from "../config/index.js";
+import type { HostResolver } from "../net/ip-guard.js";
 import type { Tool } from "../tools/types.js";
 import { type McpTrustStore } from "./trust.js";
 import { type McpTrustIO } from "./trust-gate.js";
@@ -21,12 +22,18 @@ interface ServiceLogger {
 }
 /** Explicit dependency overrides, for tests only. Production passes none. */
 export interface McpServiceDeps {
-    /** Substitute the transport (a fake peer — no real server binary). */
-    transportFactory?: (server: string, cfg: McpServerConfig, root: string) => McpTransport;
+    /** Substitute the transport (a fake peer — no real server binary/socket). */
+    transportFactory?: (server: string, cfg: McpServerConfig, root: string, 
+    /** Pre-validated, pinned address set (url servers only). */
+    addresses: string[], 
+    /** Resolved auth headers (url servers only; C.27c). */
+    authHeaders?: Record<string, string>) => McpTransport;
     /** Substitute the trust store. */
     trustStore?: McpTrustStore;
     /** ISO-timestamp source for a recorded trust decision. */
     now?: () => string;
+    /** DNS resolver for the trust gate's url-endpoint capture + SSRF guard. */
+    resolveHost?: HostResolver;
 }
 export interface ConnectMcpToolsParams {
     cwd: string;
@@ -43,6 +50,16 @@ export interface ConnectMcpToolsResult {
     tools: Tool[];
 }
 export declare function connectMcpTools(params: ConnectMcpToolsParams): Promise<ConnectMcpToolsResult>;
+/**
+ * Resolve the auth headers to send to a `url` server (C.27c), or `undefined` for
+ * an unauthenticated/stdio server. Two sources, both user-owned and outside the
+ * repo: a `credentialRef` looked up SOLELY in `~/.cruxy/credentials.json` (never
+ * the env, never any config file), and raw `headers` (accepted only from
+ * user-scope config — the loader already rejected them from project scope). A
+ * named credential with no stored token throws {@link mcpAuth} (missing) so a
+ * dangling reference fails cleanly rather than connecting unauthenticated.
+ */
+export declare function resolveMcpAuthHeaders(server: string, cfg: McpServerConfig, read?: (ref: string) => string | undefined): Record<string, string> | undefined;
 /**
  * Dispose every live MCP connection (session end / process teardown). Mirrors
  * `resetLspServices`; the shared child-tree exit backstop reaps anything a hard

package/dist/mcp/service.js

@@ -1,7 +1,9 @@
 import path from "node:path";
-import { mcpConnect } from "../errors/index.js";
+import { readMcpCredential } from "../config/credentials.js";
+import { CruxyError, ErrorCode, mcpAuth, mcpConnect } from "../errors/index.js";
 import { mcpToolsFrom } from "./adapter.js";
 import { McpClient } from "./client.js";
+import { McpHttpAuthError, McpHttpTransport } from "./http-transport.js";
 import { McpStdioTransport } from "./transport.js";
 import { fileMcpTrustStore } from "./trust.js";
 import { ensureMcpTrust } from "./trust-gate.js";
@@ -17,16 +19,32 @@ export async function connectMcpTools(params) {
         return { tools: [] };
     const root = path.resolve(params.cwd);
     // Trust gate. Non-interactive + untrusted THROWS CRUXY_E_MCP_UNTRUSTED here,
-    // before any spawn. Interactive shows the disclosure; a decline connects to
-    // nothing.
-    const outcome = await ensureMcpTrust(root, servers, {
-        store: deps?.trustStore ?? fileMcpTrustStore(),
-        interactive,
-        io,
-        now: deps?.now,
-    });
-    if (outcome === "declined") {
-        logger.info("mcp: servers not trusted — no MCP tools were loaded");
+    // before any spawn OR socket/DNS (JC-C). Interactive shows the disclosure; a
+    // decline connects to nothing. A url server refused by the SSRF guard throws
+    // CRUXY_E_MCP_BLOCKED — surfaced (coded), non-fatal to the run.
+    let endpoints;
+    try {
+        const result = await ensureMcpTrust(root, servers, {
+            store: deps?.trustStore ?? fileMcpTrustStore(),
+            interactive,
+            io,
+            now: deps?.now,
+            resolveHost: deps?.resolveHost,
+        });
+        if (result.outcome === "declined") {
+            logger.info("mcp: servers not trusted — no MCP tools were loaded");
+            return { tools: [] };
+        }
+        endpoints = result.endpoints;
+    }
+    catch (err) {
+        // Untrusted is the fail-closed supply-chain stop — stays fatal. Any other
+        // gate error (SSRF block, unresolvable endpoint) degrades the feature to
+        // "no MCP tools" with a coded, visible reason rather than crashing the run.
+        if (err instanceof CruxyError && err.code === ErrorCode.McpUntrusted)
+            throw err;
+        const coded = err instanceof CruxyError ? err : mcpConnect("url server", err);
+        logger.warn(`${coded.code}: ${coded.title} — ${coded.cause ?? ""}`);
         return { tools: [] };
     }
     const timeouts = {
@@ -40,9 +58,21 @@ export async function connectMcpTools(params) {
     };
     const tools = [];
     for (const [server, cfg] of Object.entries(servers)) {
-        const transport = makeTransport(server, cfg, root, deps);
+        // Resolve the credential (C.27c) BEFORE building the transport. A named
+        // credential with no token in ~/.cruxy fails cleanly (coded, visible) and the
+        // server simply contributes no tools — a bad reference never connects.
+        let authHeaders;
+        try {
+            authHeaders = resolveMcpAuthHeaders(server, cfg);
+        }
+        catch (err) {
+            const coded = err instanceof CruxyError ? err : mcpConnect(server, err);
+            logger.warn(`${coded.code}: ${coded.title} — ${coded.cause ?? ""}`);
+            continue;
+        }
+        const transport = makeTransport(server, cfg, root, endpoints[server] ?? [], timeouts, deps, authHeaders);
         if (!transport) {
-            logger.warn(`${mcpConnect(server).code}: server "${server}" uses an unsupported transport (only stdio \`command\` is supported)`);
+            logger.warn(`${mcpConnect(server).code}: server "${server}" uses an unsupported transport (need \`command\` (stdio) or \`url\`)`);
             continue;
         }
         const client = new McpClient(transport, timeouts);
@@ -61,20 +91,62 @@ export async function connectMcpTools(params) {
             logger.debug(`mcp: connected "${server}" (${serverTools.length} tool(s))`);
         }
         catch (err) {
-            const coded = mcpConnect(server, err);
+            // A rejected credential (401/403) is coded distinctly from a connect
+            // failure so the user knows to fix the credential, not the network.
+            const coded = err instanceof McpHttpAuthError
+                ? mcpAuth(server, { kind: "rejected", status: err.status })
+                : mcpConnect(server, err);
             logger.warn(`${coded.code}: ${coded.title} — ${coded.cause ?? ""}`);
             await client.dispose(true).catch(() => { });
         }
     }
     return { tools };
 }
-/** Build the real stdio transport for a server, or null for an unsupported one. */
-function makeTransport(server, cfg, root, deps) {
+/**
+ * Resolve the auth headers to send to a `url` server (C.27c), or `undefined` for
+ * an unauthenticated/stdio server. Two sources, both user-owned and outside the
+ * repo: a `credentialRef` looked up SOLELY in `~/.cruxy/credentials.json` (never
+ * the env, never any config file), and raw `headers` (accepted only from
+ * user-scope config — the loader already rejected them from project scope). A
+ * named credential with no stored token throws {@link mcpAuth} (missing) so a
+ * dangling reference fails cleanly rather than connecting unauthenticated.
+ */
+export function resolveMcpAuthHeaders(server, cfg, read = readMcpCredential) {
+    const headers = { ...(cfg.headers ?? {}) };
+    if (cfg.credentialRef) {
+        const token = read(cfg.credentialRef);
+        if (!token) {
+            throw mcpAuth(server, { kind: "missing", ref: cfg.credentialRef });
+        }
+        headers.Authorization = `Bearer ${token}`;
+    }
+    return Object.keys(headers).length > 0 ? headers : undefined;
+}
+/**
+ * Build the transport for a server: stdio (spawns a child) or network (an HTTP
+ * transport pinned to the already-validated `addresses`). Returns null for a
+ * server with neither. The stdio path is byte-identical to C.27 — network is a
+ * new branch, never a change to how stdio servers are constructed.
+ */
+function makeTransport(server, cfg, root, addresses, timeouts, deps, authHeaders) {
     if (deps?.transportFactory)
-        return deps.transportFactory(server, cfg, root);
-    if (!cfg.command)
-        return null; // url transport is not yet supported
-    return new McpStdioTransport({ command: cfg.command, args: cfg.args ?? [], env: cfg.env ?? {} }, root);
+        return deps.transportFactory(server, cfg, root, addresses, authHeaders);
+    if (cfg.command) {
+        return new McpStdioTransport({ command: cfg.command, args: cfg.args ?? [], env: cfg.env ?? {} }, root);
+    }
+    if (cfg.url) {
+        // Trust already resolved + SSRF-validated the URL and handed us the pinned
+        // address set; the transport opens NO socket until `initialize()` (JC-C).
+        // authHeaders reach ONLY this pinned https endpoint (transport re-checks).
+        return new McpHttpTransport({
+            url: cfg.url,
+            addresses,
+            connectTimeout: timeouts.startupTimeout,
+            requestTimeout: timeouts.requestTimeout,
+            authHeaders,
+        });
+    }
+    return null;
 }
 /**
  * Dispose every live MCP connection (session end / process teardown). Mirrors

package/dist/mcp/trust-gate.d.ts

@@ -1,19 +1,32 @@
+import { type HostResolver } from "../net/ip-guard.js";
 import type { McpServerConfig } from "../config/index.js";
 import { type McpTrustStore } from "./trust.js";
 /**
- * The connect-time trust decision (C.27). This is the gate that stands between a
- * configured MCP server and it actually running. Its wording is deliberately
- * blunt, because the escalation is real: a trusted stdio MCP server runs
- * UNSANDBOXED with your full privileges. The shell sandbox (C.16) can box a
- * command, but it cannot contain a trusted external program's own side effects —
- * so "trust this server" literally means "run this third-party code as me".
+ * The connect-time trust decision (C.27, extended for network transport in
+ * C.27b). This is the gate that stands between a configured MCP server and it
+ * actually running / being connected to.
+ *
+ * For a STDIO server the escalation is "run this third-party code UNSANDBOXED with
+ * your full privileges." For a NETWORK (`url`) server the escalation is different
+ * and is disclosed differently: cruxy does NOT run the server's code locally, but
+ * it will SEND your tool arguments to a remote endpoint over the network and treat
+ * its responses as untrusted data. Both are real; the wording branches so neither
+ * is over- nor under-stated.
  *
  * Behavior:
- * - Already trusted (config fingerprint matches a recorded decision) → proceed.
- * - Untrusted + interactive → show the disclosure, read one key; only `y` trusts
- *   (records the decision) and proceeds. Anything else (incl. EOF) → declined.
+ * - Already trusted → proceed. "Trusted" means the config fingerprint matches AND,
+ *   for url servers, the resolved IP set still matches the set bound at trust time
+ *   (JC-D). A changed IP set is treated like a changed command → stale → re-gate.
+ * - Untrusted + interactive → show the disclosure, read one key; only `y` trusts.
  * - Untrusted + NON-interactive → throw {@link mcpUntrusted} (CRUXY_E_MCP_UNTRUSTED)
- *   BEFORE anything is spawned. Non-interactive NEVER auto-trusts.
+ *   BEFORE any socket or DNS lookup. For network, CONNECTING IS THE ACTION, so a
+ *   never-trusted config fails closed with ZERO network I/O (JC-C).
+ *
+ * Ordering that guarantees zero-DNS-before-trust: the "is any decision recorded?"
+ * and static-fingerprint checks are pure (no I/O). Endpoint resolution (DNS + the
+ * SSRF guard) runs ONLY after a recorded, static-matching config is found (to
+ * re-validate a previously-trusted repo) or after the user presses `y` (to record
+ * a fresh decision) — never on the path that throws for an untrusted clone.
  */
 /** The minimal prompt surface — satisfied by the shared `defaultPromptIO`. */
 export interface McpTrustIO {
@@ -30,6 +43,17 @@ export interface EnsureMcpTrustDeps {
     io?: McpTrustIO;
     /** ISO-timestamp source for the recorded decision (injected for tests). */
     now?: () => string;
+    /** DNS resolver for url-server endpoint capture (injected for tests). */
+    resolveHost?: HostResolver;
 }
 export type McpTrustOutcome = "trusted" | "declined";
-export declare function ensureMcpTrust(root: string, servers: Record<string, McpServerConfig>, deps: EnsureMcpTrustDeps): Promise<McpTrustOutcome>;
+export interface EnsureMcpTrustResult {
+    outcome: McpTrustOutcome;
+    /**
+     * Validated, pinned address sets per url server (empty for stdio/declined). The
+     * SAME set that was compared for trust — the caller pins the connection to it so
+     * the addresses trusted are exactly the addresses dialed (no second resolve).
+     */
+    endpoints: Record<string, string[]>;
+}
+export declare function ensureMcpTrust(root: string, servers: Record<string, McpServerConfig>, deps: EnsureMcpTrustDeps): Promise<EnsureMcpTrustResult>;

package/dist/mcp/trust-gate.js

@@ -1,40 +1,105 @@
-import { mcpUntrusted } from "../errors/index.js";
+import path from "node:path";
+import { mcpBlocked, mcpUntrusted } from "../errors/index.js";
+import { BlockedHostError, defaultResolveHost, } from "../net/ip-guard.js";
 import { themeForColor } from "../theme/index.js";
-import { fingerprintMcpServers, isMcpTrusted, } from "./trust.js";
+import { resolveMcpEndpoints } from "./url-guard.js";
+import { endpointsMatch, fingerprintMcpServers, } from "./trust.js";
 export async function ensureMcpTrust(root, servers, deps) {
     const names = Object.keys(servers);
     const fingerprint = fingerprintMcpServers(servers);
-    if (isMcpTrusted(deps.store, root, fingerprint))
-        return "trusted";
-    // Non-interactive: fail closed, before any spawn. Never auto-trust.
+    const hasUrlServer = names.some((n) => servers[n].url);
+    const resolveHost = deps.resolveHost ?? defaultResolveHost;
+    // Pure, no-I/O check first — an untrusted clone throws below with zero DNS.
+    const record = deps.store.get(path.resolve(root));
+    const staticMatch = record !== undefined && record.fingerprint === fingerprint;
+    if (staticMatch) {
+        if (!hasUrlServer)
+            return { outcome: "trusted", endpoints: {} };
+        // A previously-trusted config with url servers: re-resolve + re-validate now
+        // (SSRF guard) and compare the IP set to the one bound at trust time (JC-D).
+        // This DNS runs only for an already-recorded config, never for a clone.
+        const current = await resolveEndpointsOrBlocked(servers, resolveHost);
+        if (endpointsMatch(record.endpoints, current)) {
+            return { outcome: "trusted", endpoints: current };
+        }
+        // IP set drifted → stale → fall through and re-gate (endpointChanged=true).
+    }
+    // Not trusted (no record / static mismatch / endpoint drift).
     if (!deps.interactive || !deps.io) {
+        // Fail closed BEFORE any spawn/connect. Non-interactive NEVER auto-trusts.
         throw mcpUntrusted(root, names);
     }
     const io = deps.io;
-    io.write(disclosure(names, io.color));
+    io.write(disclosure(names, servers, io.color, staticMatch));
     const key = (await io.readKey()).toLowerCase();
     io.write("\n");
-    if (key === "y") {
-        const now = deps.now ?? (() => new Date().toISOString());
-        deps.store.record({ root, fingerprint, at: now() });
-        return "trusted";
+    if (key !== "y")
+        return { outcome: "declined", endpoints: {} };
+    // Trust granted. Capture the current endpoint set (DNS + SSRF guard) and bind it
+    // into the decision. If validation refuses (SSRF/scheme), do NOT record trust.
+    const endpoints = hasUrlServer
+        ? await resolveEndpointsOrBlocked(servers, resolveHost)
+        : {};
+    const now = deps.now ?? (() => new Date().toISOString());
+    deps.store.record({ root, fingerprint, at: now(), endpoints });
+    return { outcome: "trusted", endpoints };
+}
+/** Resolve endpoints, translating an SSRF/scheme refusal into a coded error. */
+async function resolveEndpointsOrBlocked(servers, resolveHost) {
+    try {
+        return await resolveMcpEndpoints(servers, resolveHost);
+    }
+    catch (err) {
+        if (err instanceof BlockedHostError) {
+            // Find the offending url server for the coded error's server name.
+            const offending = Object.keys(servers).find((id) => servers[id].url) ?? "url server";
+            throw mcpBlocked(offending, err.message);
+        }
+        throw err; // HostUnresolvedError → surfaced by the caller as a connect failure
     }
-    return "declined";
 }
 /** The explicit escalation disclosure shown before trusting any server. */
-function disclosure(names, color) {
+function disclosure(names, servers, color, endpointChanged) {
     const t = themeForColor(color);
-    const list = names.map((n) => `    • ${n}`).join("\n");
-    return [
+    const list = names
+        .map((n) => `    • ${n} ${t.muted(describeTransport(servers[n]))}`)
+        .join("\n");
+    const hasUrl = names.some((n) => servers[n].url);
+    const hasStdio = names.some((n) => servers[n].command);
+    const lines = [
         `${t.danger(t.strong("! MCP servers want to connect"))} ${t.muted(`(${names.length})`)}`,
         list,
         "",
-        t.strong("  Trusting these servers runs their code on your machine with your FULL"),
-        t.strong("  privileges — they are NOT sandboxed. A trusted server can read and write"),
-        t.strong("  your files and make network calls, just like a program you ran yourself."),
-        t.muted("  Their tools are still individually approved before each call, and their"),
-        t.muted("  output is treated as untrusted data — but the process itself is not boxed."),
-        "",
-        `  ${t.muted("Trust and connect these servers for this repo?")} ${t.strong("[y/N]")} `,
-    ].join("\n");
+    ];
+    if (endpointChanged) {
+        lines.push(t.danger(t.strong("  A remote server's IP address set has CHANGED since you trusted it.")), t.muted("  The endpoint behind the URL may have moved — re-confirm before connecting."), "");
+    }
+    if (hasStdio) {
+        lines.push(t.strong("  Trusting a stdio server runs its code on your machine with your FULL"), t.strong("  privileges — it is NOT sandboxed, just like a program you ran yourself."));
+    }
+    if (hasUrl) {
+        lines.push(t.strong("  For a url server, cruxy sends your tool arguments to a REMOTE endpoint"), t.strong("  over the network (https, cert-validated, pinned to a public IP)."), t.muted("  Note: trusting a remote endpoint is WEAKER than a local binary — it can"), t.muted("  change its behavior with no change you can see. Only its URL + current IP"), t.muted("  set are bound to this decision."));
+        // Credential disclosure (C.27c): a server that RECEIVES a credential is a
+        // materially bigger grant — name it explicitly so the grant is never silent.
+        const credLines = names
+            .filter((n) => servers[n].credentialRef || servers[n].headers)
+            .map((n) => {
+            const ref = servers[n].credentialRef;
+            const what = ref
+                ? `your "${ref}" credential`
+                : "your configured auth headers";
+            return t.danger(t.strong(`  • "${n}" will RECEIVE ${what} on every request.`));
+        });
+        if (credLines.length)
+            lines.push("", ...credLines);
+    }
+    lines.push(t.muted("  Their tools are still individually approved before each call, and their"), t.muted("  output is treated as untrusted data."), "", `  ${t.muted("Trust and connect these servers for this repo?")} ${t.strong("[y/N]")} `);
+    return lines.join("\n");
+}
+/** A short "(stdio: …)" / "(url: …)" descriptor for the disclosure list. */
+function describeTransport(cfg) {
+    if (cfg.command) {
+        return `(stdio: ${[cfg.command, ...(cfg.args ?? [])].join(" ")})`;
+    }
+    return cfg.url ? `(url: ${cfg.url})` : "(no transport)";
 }

package/dist/mcp/trust.d.ts

@@ -21,14 +21,24 @@ export declare function mcpTrustPath(): string;
  * construction so a benign reformat of the config (reindent, reordered keys)
  * does NOT change it, while any real change to what would be executed DOES:
  * - only the meaning-bearing fields are hashed (server id, command, args, url,
- *   and env as sorted key=value pairs);
- * - args/env are normalized to a fixed order;
+ *   env as sorted key=value pairs, the auth `credentialRef`, and the NAMES of any
+ *   raw auth headers — never a secret value: the token/header VALUE is never
+ *   hashed, so rotating a credential does NOT re-gate, but SWAPPING which
+ *   credential (or header) a server sends DOES — defeating trust-then-swap-cred);
+ * - args/env/header-names are normalized to a fixed order;
  * - servers are sorted by id and serialized with a fixed field order.
  *
  * The empty set has a fixed, stable fingerprint (trusting "no servers" is
  * meaningful; adding the first server re-gates).
  */
 export declare function fingerprintMcpServers(servers: Record<string, McpServerConfig>): string;
+/**
+ * Do two url-server endpoint maps bind the SAME address sets? (JC-D.) Both sides
+ * are expected pre-sorted/deduped (`normalizeAddressSet`); a differing server set
+ * or any differing address list is a mismatch → trust is stale → re-gate. The
+ * empty map equals the empty map (a stdio-only config has no endpoints to drift).
+ */
+export declare function endpointsMatch(a?: Record<string, string[]>, b?: Record<string, string[]>): boolean;
 /** The persisted trust seam — file-backed in production, injectable for tests. */
 export interface McpTrustStore {
     /** The recorded decision for a repo root, or undefined if never trusted. */

package/dist/mcp/trust.js

@@ -26,8 +26,11 @@ export function mcpTrustPath() {
  * construction so a benign reformat of the config (reindent, reordered keys)
  * does NOT change it, while any real change to what would be executed DOES:
  * - only the meaning-bearing fields are hashed (server id, command, args, url,
- *   and env as sorted key=value pairs);
- * - args/env are normalized to a fixed order;
+ *   env as sorted key=value pairs, the auth `credentialRef`, and the NAMES of any
+ *   raw auth headers — never a secret value: the token/header VALUE is never
+ *   hashed, so rotating a credential does NOT re-gate, but SWAPPING which
+ *   credential (or header) a server sends DOES — defeating trust-then-swap-cred);
+ * - args/env/header-names are normalized to a fixed order;
  * - servers are sorted by id and serialized with a fixed field order.
  *
  * The empty set has a fixed, stable fingerprint (trusting "no servers" is
@@ -43,10 +46,31 @@ export function fingerprintMcpServers(servers) {
         Object.entries(s.env ?? {})
             .map(([k, v]) => `${k}=${v}`)
             .sort(),
+        s.credentialRef ?? "",
+        // Header NAMES only — never the secret values (see fn doc: rotation must
+        // not re-gate; a changed set of headers sent must).
+        Object.keys(s.headers ?? {}).sort(),
     ])
         .sort((a, b) => String(a[0]).localeCompare(String(b[0])));
     return createHash("sha256").update(JSON.stringify(canonical)).digest("hex");
 }
+/**
+ * Do two url-server endpoint maps bind the SAME address sets? (JC-D.) Both sides
+ * are expected pre-sorted/deduped (`normalizeAddressSet`); a differing server set
+ * or any differing address list is a mismatch → trust is stale → re-gate. The
+ * empty map equals the empty map (a stdio-only config has no endpoints to drift).
+ */
+export function endpointsMatch(a = {}, b = {}) {
+    const ka = Object.keys(a).sort();
+    const kb = Object.keys(b).sort();
+    if (ka.length !== kb.length || ka.some((k, i) => k !== kb[i]))
+        return false;
+    return ka.every((k) => {
+        const av = a[k];
+        const bv = b[k];
+        return av.length === bv.length && av.every((x, i) => x === bv[i]);
+    });
+}
 /**
  * Is this repo's current MCP server config trusted? True only when a decision
  * exists AND its fingerprint matches the current one — a changed config is

package/dist/mcp/types.d.ts

@@ -17,6 +17,16 @@ export interface McpTrust {
     fingerprint: string;
     /** ISO timestamp the decision was recorded. */
     at: string;
+    /**
+     * Network (`url`) servers only (C.27b, JC-D): the sorted, deduped IP-address set
+     * each url server resolved to AT TRUST TIME. Bound into the decision so that if a
+     * remote endpoint's address set later changes, trust goes stale and re-gates —
+     * the network analog of the C.19 command-swap check. Absent/`{}` for a stdio-only
+     * config. HONEST LIMIT: this is WEAKER than stdio's binary fingerprint — a remote
+     * service can change its behavior with no observable change to URL or IP set. That
+     * is inherent to trusting a remote endpoint; it is disclosed, not papered over.
+     */
+    endpoints?: Record<string, string[]>;
 }
 /**
  * The transport seam — JSON-RPC over some duplex channel (stdio in production).

package/dist/mcp/url-guard.d.ts

@@ -0,0 +1,48 @@
+import type { McpServerConfig } from "../config/index.js";
+import { type HostResolver } from "../net/ip-guard.js";
+/**
+ * The network-MCP URL policy (C.27b, JC-E). A `url` MCP server is a NEW trust
+ * boundary stdio never had: the endpoint is off-box and reached over a wire we do
+ * not control. This module is the ONE place a URL is turned into a validated,
+ * pin-ready address set, so the scheme + SSRF rules are enforced by construction
+ * and can be audited in one spot. It reuses the shared {@link ../net/ip-guard}
+ * range math (JC-A) — it does NOT re-implement any address checks.
+ *
+ * Policy:
+ * - `https://` → every resolved address MUST be public (SSRF gate); the socket is
+ *   later pinned to exactly those addresses so a rebind can't flip check→connect.
+ *   TLS certificate validation is undici's default and is NEVER disabled (there is
+ *   deliberately no skip-verify option — it is the kind of footgun that ends up set
+ *   in prod).
+ * - `http://` → permitted ONLY when every resolved address is loopback (a local
+ *   dev server). Plaintext to any non-loopback host is refused — use `https`.
+ * - anything else (`file:`, `ws:`, `data:`…) → refused.
+ *
+ * A refusal throws {@link BlockedHostError}; an unresolvable host throws
+ * {@link HostUnresolvedError}. The service layer maps these to coded errors
+ * (`CRUXY_E_MCP_BLOCKED` / `CRUXY_E_MCP_CONNECT`) — never a silent skip.
+ */
+export interface ValidatedMcpUrl {
+    /** The parsed URL (host header / TLS SNI still carry this hostname). */
+    url: URL;
+    /** The validated, sorted, deduped address set to pin the connection to. */
+    addresses: string[];
+}
+/**
+ * Validate one MCP server URL against the scheme + SSRF policy and return the
+ * address set to pin to. Resolution goes through the injected {@link HostResolver}
+ * so tests are deterministic and so the SAME resolved set can feed both the trust
+ * fingerprint (JC-D) and the connection pin (no second, rebind-able resolve).
+ */
+export declare function validateMcpUrl(rawUrl: string, resolve: HostResolver): Promise<ValidatedMcpUrl>;
+/**
+ * Resolve + validate every `url` server's endpoint, returning a map of server id
+ * → sorted address set. stdio servers are skipped (they have no network endpoint).
+ * Throws {@link BlockedHostError}/{@link HostUnresolvedError} on the first refusal
+ * — the caller records trust / opens a socket only if ALL url servers validate.
+ *
+ * This is the single resolution used for BOTH the JC-D fingerprint (the IP set is
+ * bound into the trust decision) and the connection pin, so the addresses trusted
+ * are exactly the addresses dialed.
+ */
+export declare function resolveMcpEndpoints(servers: Record<string, McpServerConfig>, resolve: HostResolver): Promise<Record<string, string[]>>;

package/dist/mcp/url-guard.js

@@ -0,0 +1,62 @@
+import { assertAllPublic, BlockedHostError, HostUnresolvedError, isLoopbackAddress, normalizeAddressSet, } from "../net/ip-guard.js";
+/**
+ * Validate one MCP server URL against the scheme + SSRF policy and return the
+ * address set to pin to. Resolution goes through the injected {@link HostResolver}
+ * so tests are deterministic and so the SAME resolved set can feed both the trust
+ * fingerprint (JC-D) and the connection pin (no second, rebind-able resolve).
+ */
+export async function validateMcpUrl(rawUrl, resolve) {
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        throw new BlockedHostError(`"${rawUrl}" is not a valid absolute URL`);
+    }
+    const host = url.hostname.replace(/^\[|\]$/g, "");
+    if (url.protocol === "https:") {
+        const addresses = await assertAllPublic(host, resolve);
+        return { url, addresses: normalizeAddressSet(addresses) };
+    }
+    if (url.protocol === "http:") {
+        let addresses;
+        try {
+            addresses = await resolve(host);
+        }
+        catch (err) {
+            throw new HostUnresolvedError(`could not resolve host "${host}": ${err.message}`);
+        }
+        if (addresses.length === 0) {
+            throw new HostUnresolvedError(`host "${host}" resolved to no addresses`);
+        }
+        for (const addr of addresses) {
+            if (!isLoopbackAddress(addr)) {
+                throw new BlockedHostError(`http MCP URL "${rawUrl}" resolves to ${addr}; plaintext http is only ` +
+                    `permitted for loopback dev servers — use https for a remote server`);
+            }
+        }
+        return { url, addresses: normalizeAddressSet(addresses) };
+    }
+    throw new BlockedHostError(`an MCP server URL must be https (or http to a loopback dev server); ` +
+        `got "${url.protocol.replace(/:$/, "")}"`);
+}
+/**
+ * Resolve + validate every `url` server's endpoint, returning a map of server id
+ * → sorted address set. stdio servers are skipped (they have no network endpoint).
+ * Throws {@link BlockedHostError}/{@link HostUnresolvedError} on the first refusal
+ * — the caller records trust / opens a socket only if ALL url servers validate.
+ *
+ * This is the single resolution used for BOTH the JC-D fingerprint (the IP set is
+ * bound into the trust decision) and the connection pin, so the addresses trusted
+ * are exactly the addresses dialed.
+ */
+export async function resolveMcpEndpoints(servers, resolve) {
+    const out = {};
+    for (const [id, cfg] of Object.entries(servers)) {
+        if (!cfg.url)
+            continue;
+        const { addresses } = await validateMcpUrl(cfg.url, resolve);
+        out[id] = addresses;
+    }
+    return out;
+}

package/dist/net/ip-guard.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The ONE owner of "is this IP allowed to be reached" (JC-A). The SSRF address
+ * math — parsing and range-classifying v4/v6 literals, including IPv4-mapped and
+ * alternate encodings — lives here and nowhere else. Both the web subsystem
+ * (`web/ssrf.ts`, C.20) and the network MCP transport (`mcp/http-transport.ts`,
+ * C.27b) consume it, so there is exactly one implementation of the range rules
+ * and one place to audit them.
+ *
+ * The two connection-facing helpers a caller needs are also here:
+ * - {@link assertAllPublic} — resolve a host and require EVERY address be public;
+ * - {@link pinnedLookup} — a `dns.lookup` shim that pins a connection to a set of
+ *   already-validated addresses (defeats DNS rebinding). Each subsystem wraps it
+ *   in its OWN undici `Agent` (the web one-shot fetch vs. MCP's long-lived
+ *   POST + SSE shape differ), but the pinning logic is shared.
+ */
+/** Resolve a hostname to its IP addresses (injected so the guard is testable). */
+export type HostResolver = (host: string) => Promise<string[]>;
+/** Default resolver: node's `dns.lookup` returning ALL addresses. */
+export declare const defaultResolveHost: HostResolver;
+/** Thrown when a URL/host is refused pre-dispatch; carries a human reason. */
+export declare class BlockedHostError extends Error {
+}
+/** Thrown when the host could not be resolved (a network failure, not a block). */
+export declare class HostUnresolvedError extends Error {
+}
+/** True if an address (v4 or v6) is in a range that must never be reached. */
+export declare function isBlockedAddress(addr: string): boolean;
+/**
+ * True if an address is a LOOPBACK address (127.0.0.0/8, ::1, or an IPv4-mapped
+ * loopback). This is the ONLY range the network MCP transport permits over plain
+ * `http` (loopback dev servers); everything else must be `https` to a public IP.
+ * An unparseable address is not loopback (fail closed — it won't get the http pass).
+ */
+export declare function isLoopbackAddress(addr: string): boolean;
+/**
+ * Resolve `host` and require that EVERY resolved address is public — the SSRF
+ * gate for any URL a caller did not fully control. Throws {@link BlockedHostError}
+ * if any address is private/loopback/link-local/reserved (a security refusal), or
+ * {@link HostUnresolvedError} if the host cannot be resolved (a network failure).
+ * Returns the validated addresses so the caller can PIN the connection to them.
+ */
+export declare function assertAllPublic(host: string, resolve: HostResolver): Promise<string[]>;
+/**
+ * A `dns.lookup`-compatible function that ignores the hostname and always hands
+ * back one of the pre-validated `addresses`. This is what pins a connection to the
+ * address the SSRF check already approved, defeating DNS rebinding: the socket can
+ * only reach a validated IP, never a value re-resolved at connect time. The Host
+ * header / TLS SNI still carry the original hostname (only the dialed IP is pinned).
+ */
+export declare function pinnedLookup(addresses: string[]): (_hostname: string, options: unknown, callback: (err: NodeJS.ErrnoException | null, address: string | {
+    address: string;
+    family: number;
+}[], family?: number) => void) => void;
+/** Sort + dedupe an address set so equality checks are order-insensitive. */
+export declare function normalizeAddressSet(addresses: string[]): string[];