@cruxy/cli 0.25.0 → 0.27.0

package/dist/mcp/http-transport.js

@@ -0,0 +1,299 @@
+import { Agent, fetch as undiciFetch } from "undici";
+import { pinnedLookup } from "../net/ip-guard.js";
+/**
+ * The endpoint rejected our credential (401/403) — C.27c. A DISTINCT type so the
+ * service maps it to `CRUXY_E_MCP_AUTH` ("credential rejected") rather than the
+ * generic connect failure. Carries only the status; the token never touches it.
+ */
+export class McpHttpAuthError extends Error {
+    status;
+    constructor(status) {
+        super(`MCP endpoint rejected the credential (${status})`);
+        this.status = status;
+        this.name = "McpHttpAuthError";
+    }
+}
+/** Framing headers a credential/user header can never override (case-insensitive). */
+const RESERVED_HEADERS = new Set(["content-type", "accept", "mcp-session-id"]);
+/** Drop any reserved framing header so auth headers can only ADD, never rewrite. */
+function sanitizeAuthHeaders(headers) {
+    const out = {};
+    for (const [k, v] of Object.entries(headers ?? {})) {
+        if (!RESERVED_HEADERS.has(k.toLowerCase()))
+            out[k] = v;
+    }
+    return out;
+}
+/** The URL's protocol, or "" if unparseable (never throws). */
+function safeProtocol(url) {
+    try {
+        return new URL(url).protocol;
+    }
+    catch {
+        return "";
+    }
+}
+export class McpHttpTransport {
+    url;
+    connectTimeout;
+    requestTimeout;
+    dispatcher;
+    fetchImpl;
+    /** Sanitized auth headers, sent ONLY over https to this pinned endpoint. */
+    authHeaders;
+    nextId = 1;
+    disposed = false;
+    /** Streamable HTTP session id, captured from the `initialize` response. */
+    sessionId = null;
+    crashHandler = null;
+    /** In-flight request aborts, so `dispose()` can cancel them. */
+    inflight = new Set();
+    constructor(spec, fetchImpl = undiciFetch) {
+        this.url = spec.url;
+        this.connectTimeout = spec.connectTimeout;
+        this.requestTimeout = spec.requestTimeout;
+        this.fetchImpl = fetchImpl;
+        // Credential floor (C.27c, JC-3): a credential is sent ONLY over https. This
+        // is belt-and-suspenders to the schema's https refine — if an authed spec ever
+        // reaches here with a non-https url, we drop the headers rather than transmit
+        // a bearer token over plaintext (including loopback — no dev carve-out).
+        const wantsAuth = Object.keys(spec.authHeaders ?? {}).length > 0;
+        const isHttps = safeProtocol(spec.url) === "https:";
+        this.authHeaders =
+            wantsAuth && isHttps ? sanitizeAuthHeaders(spec.authHeaders) : {};
+        // Our OWN Agent, tuned for the POST + SSE shape (distinct from web's one-shot
+        // fetch dispatcher). Pinned to the validated addresses; no redirects. Building
+        // an Agent opens no socket — the first connection is deferred to initialize().
+        this.dispatcher = spec.addresses.length
+            ? new Agent({
+                connect: { lookup: pinnedLookup(spec.addresses) },
+                maxRedirections: 0,
+            })
+            : new Agent({ maxRedirections: 0 });
+    }
+    /** Whether the `initialize` handshake budget or the per-call budget applies. */
+    budgetFor(method) {
+        return method === "tools/call" ? this.requestTimeout : this.connectTimeout;
+    }
+    async request(method, params, timeoutMs) {
+        if (this.disposed)
+            throw new Error("transport disposed");
+        const id = this.nextId++;
+        const budget = Math.min(timeoutMs, this.budgetFor(method));
+        const controller = new AbortController();
+        this.inflight.add(controller);
+        const timer = setTimeout(() => controller.abort(), budget);
+        timer.unref?.();
+        try {
+            const res = await this.post(JSON.stringify({ jsonrpc: "2.0", id, method, params }), controller.signal, method);
+            // Streamable HTTP: the response is either a single JSON body or an SSE
+            // stream carrying the JSON-RPC response event. Capture the session id from
+            // the initialize response so later requests are correlated to the session.
+            const sid = res.headers.get("mcp-session-id");
+            if (sid)
+                this.sessionId = sid;
+            const contentType = (res.headers.get("content-type") ?? "").toLowerCase();
+            const msg = contentType.includes("text/event-stream")
+                ? await readSseResponse(res, id)
+                : await readJsonResponse(res, id);
+            if (msg.error)
+                throw new Error(msg.error.message ?? "MCP error");
+            return msg.result;
+        }
+        finally {
+            clearTimeout(timer);
+            this.inflight.delete(controller);
+        }
+    }
+    notify(method, params) {
+        if (this.disposed)
+            return;
+        const controller = new AbortController();
+        this.inflight.add(controller);
+        const timer = setTimeout(() => controller.abort(), this.connectTimeout);
+        timer.unref?.();
+        // Fire-and-forget: a notification has no id and no response body to await.
+        this.post(JSON.stringify({ jsonrpc: "2.0", method, params }), controller.signal, method)
+            .catch(() => {
+            /* a dropped notification is not fatal; requests carry the real errors */
+        })
+            .finally(() => {
+            clearTimeout(timer);
+            this.inflight.delete(controller);
+        });
+    }
+    onCrash(handler) {
+        this.crashHandler = handler;
+    }
+    async dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        // Cancel every in-flight request/notification.
+        for (const c of this.inflight)
+            c.abort();
+        this.inflight.clear();
+        // Best-effort Streamable HTTP session teardown, then close the dispatcher.
+        if (this.sessionId) {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), this.connectTimeout);
+            timer.unref?.();
+            try {
+                await this.fetchImpl(this.url, {
+                    method: "DELETE",
+                    redirect: "manual",
+                    signal: controller.signal,
+                    dispatcher: this.dispatcher,
+                    // Same pinned https endpoint — the server may require auth to end the
+                    // session. Session-id last so it always wins over any auth header.
+                    headers: { ...this.authHeaders, "mcp-session-id": this.sessionId },
+                });
+            }
+            catch {
+                /* the server may be gone; teardown is best-effort */
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        }
+        await this.dispatcher.close().catch(() => { });
+    }
+    /** POST one framed JSON-RPC message; refuse redirects; reject non-2xx. */
+    async post(body, signal, method) {
+        let res;
+        try {
+            res = await this.fetchImpl(this.url, {
+                method: "POST",
+                redirect: "manual",
+                signal,
+                dispatcher: this.dispatcher,
+                headers: {
+                    // Auth first so the fixed framing headers below always win — a
+                    // credential can never rewrite content-type/accept/session framing.
+                    ...this.authHeaders,
+                    "content-type": "application/json",
+                    accept: "application/json, text/event-stream",
+                    ...(this.sessionId ? { "mcp-session-id": this.sessionId } : {}),
+                },
+                body,
+            });
+        }
+        catch (err) {
+            // A genuine connection failure (not a teardown we triggered) is the network
+            // analog of a stdio crash — notify, mirroring McpStdioTransport.onExit.
+            if (!this.disposed && !signal.aborted) {
+                this.crashHandler?.({ code: null, signal: null });
+            }
+            throw new Error(`MCP request "${method}" failed: ${err.message}`);
+        }
+        if (res.status >= 300 && res.status < 400) {
+            // An MCP endpoint has no legitimate reason to redirect (JC: maxRedirections 0).
+            throw new Error(`MCP endpoint returned a ${res.status} redirect; MCP URLs must not redirect`);
+        }
+        if (res.status === 202)
+            return res; // accepted notification, no body
+        if (res.status === 401 || res.status === 403) {
+            // Credential rejected — a DISTINCT failure from an unreachable server. The
+            // service maps this to CRUXY_E_MCP_AUTH. The status only; never the token.
+            throw new McpHttpAuthError(res.status);
+        }
+        if (!res.ok) {
+            throw new Error(`MCP endpoint responded ${res.status} ${res.statusText}`);
+        }
+        return res;
+    }
+}
+/** Parse a single JSON response body and select the message for our request id. */
+async function readJsonResponse(res, id) {
+    let parsed;
+    try {
+        parsed = await res.json();
+    }
+    catch {
+        throw new Error("malformed MCP response (invalid JSON)");
+    }
+    const found = selectResponse(parsed, id);
+    if (!found)
+        throw new Error("MCP response contained no result for the request");
+    return found;
+}
+/**
+ * Read an SSE stream and return the first JSON-RPC RESPONSE matching our id.
+ * Server→client requests (method + id) embedded in the stream are declined by
+ * being ignored — cruxy solicits none and acts on none. Notifications are ignored.
+ */
+async function readSseResponse(res, id) {
+    const reader = res.body?.getReader?.();
+    if (!reader)
+        return readJsonResponse(res, id);
+    const decoder = new TextDecoder("utf-8", { fatal: false });
+    let buffer = "";
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (value)
+            buffer += decoder.decode(value, { stream: true });
+        // SSE events are separated by a blank line; process every complete event.
+        let sep;
+        while ((sep = indexOfEventBoundary(buffer)) !== -1) {
+            const rawEvent = buffer.slice(0, sep);
+            buffer = buffer.slice(sep).replace(/^(\r?\n){1,2}/, "");
+            const data = sseData(rawEvent);
+            if (data === undefined)
+                continue;
+            let msg;
+            try {
+                msg = JSON.parse(data);
+            }
+            catch {
+                continue; // ignore unparseable event data
+            }
+            const found = selectResponse(msg, id);
+            if (found) {
+                await reader.cancel().catch(() => { });
+                return found;
+            }
+            // else: a server→client request or notification — ignored (declined).
+        }
+        if (done)
+            break;
+    }
+    throw new Error("MCP stream ended without a response for the request");
+}
+/** Index just past an SSE event boundary (blank line), or -1 if none yet. */
+function indexOfEventBoundary(buf) {
+    const a = buf.indexOf("\n\n");
+    const b = buf.indexOf("\r\n\r\n");
+    if (a === -1)
+        return b === -1 ? -1 : b;
+    if (b === -1)
+        return a;
+    return Math.min(a, b);
+}
+/** Concatenate the `data:` lines of one SSE event, or undefined if none. */
+function sseData(event) {
+    const parts = [];
+    for (const line of event.split(/\r?\n/)) {
+        if (line.startsWith("data:"))
+            parts.push(line.slice(5).replace(/^ /, ""));
+    }
+    return parts.length ? parts.join("\n") : undefined;
+}
+/**
+ * From a parsed message (object or JSON-RPC batch array), pick the RESPONSE whose
+ * id matches — i.e. it has a result/error and no `method` (a request/notification
+ * has a `method`). Returns null if none matches.
+ */
+function selectResponse(parsed, id) {
+    const entries = Array.isArray(parsed) ? parsed : [parsed];
+    for (const entry of entries) {
+        if (!entry || typeof entry !== "object")
+            continue;
+        const m = entry;
+        if (m.id === id &&
+            m.method === undefined &&
+            (m.result !== undefined || m.error !== undefined)) {
+            return m;
+        }
+    }
+    return null;
+}

package/dist/mcp/index.d.ts

@@ -1,6 +1,8 @@
 export type { McpTrust, McpTransport, RawMcpTool, McpCallResult, } from "./types.js";
-export { mcpTrustPath, fingerprintMcpServers, isMcpTrusted, fileMcpTrustStore, memoryMcpTrustStore, type McpTrustStore, } from "./trust.js";
-export { ensureMcpTrust, type EnsureMcpTrustDeps, type McpTrustIO, type McpTrustOutcome, } from "./trust-gate.js";
+export { mcpTrustPath, fingerprintMcpServers, isMcpTrusted, endpointsMatch, fileMcpTrustStore, memoryMcpTrustStore, type McpTrustStore, } from "./trust.js";
+export { ensureMcpTrust, type EnsureMcpTrustDeps, type EnsureMcpTrustResult, type McpTrustIO, type McpTrustOutcome, } from "./trust-gate.js";
+export { validateMcpUrl, resolveMcpEndpoints, type ValidatedMcpUrl, } from "./url-guard.js";
+export { McpHttpTransport, McpHttpAuthError, type McpHttpSpec, } from "./http-transport.js";
 export { demarcateDescription, demarcateResult } from "./demarcate.js";
 export { boundToolList, type McpBounds, type BoundedTool, type BoundedToolList, } from "./bounds.js";
 export { McpStdioTransport, type McpSpawnSpec } from "./transport.js";

package/dist/mcp/index.js

@@ -1,5 +1,7 @@
-export { mcpTrustPath, fingerprintMcpServers, isMcpTrusted, fileMcpTrustStore, memoryMcpTrustStore, } from "./trust.js";
+export { mcpTrustPath, fingerprintMcpServers, isMcpTrusted, endpointsMatch, fileMcpTrustStore, memoryMcpTrustStore, } from "./trust.js";
 export { ensureMcpTrust, } from "./trust-gate.js";
+export { validateMcpUrl, resolveMcpEndpoints, } from "./url-guard.js";
+export { McpHttpTransport, McpHttpAuthError, } from "./http-transport.js";
 export { demarcateDescription, demarcateResult } from "./demarcate.js";
 export { boundToolList, } from "./bounds.js";
 export { McpStdioTransport } from "./transport.js";

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>;