@cruxy/cli 0.25.0 → 0.27.0

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

package/dist/net/ip-guard.js

@@ -0,0 +1,229 @@
+import { lookup } from "node:dns";
+/** Default resolver: node's `dns.lookup` returning ALL addresses. */
+export const defaultResolveHost = (host) => new Promise((resolve, reject) => {
+    lookup(host, { all: true }, (err, addresses) => {
+        if (err)
+            reject(err);
+        else
+            resolve(addresses.map((a) => a.address));
+    });
+});
+/** Thrown when a URL/host is refused pre-dispatch; carries a human reason. */
+export class BlockedHostError extends Error {
+}
+/** Thrown when the host could not be resolved (a network failure, not a block). */
+export class HostUnresolvedError extends Error {
+}
+/** Parse a dotted-quad IPv4 string into its four octets, or null. */
+function parseIpv4(ip) {
+    const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(ip);
+    if (!m)
+        return null;
+    const octets = m.slice(1, 5).map((s) => Number(s));
+    if (octets.some((o) => o > 255))
+        return null;
+    return octets;
+}
+/** True if an IPv4 address falls in a private/loopback/link-local/reserved range. */
+function isBlockedIpv4(ip) {
+    const octets = parseIpv4(ip);
+    if (!octets)
+        return false;
+    const [a, b] = octets;
+    if (a === 0)
+        return true; // 0.0.0.0/8 "this network" / unspecified
+    if (a === 10)
+        return true; // 10.0.0.0/8 private
+    if (a === 127)
+        return true; // 127.0.0.0/8 loopback
+    if (a === 169 && b === 254)
+        return true; // 169.254.0.0/16 link-local (incl. 169.254.169.254 metadata)
+    if (a === 172 && b >= 16 && b <= 31)
+        return true; // 172.16.0.0/12 private
+    if (a === 192 && b === 168)
+        return true; // 192.168.0.0/16 private
+    if (a === 100 && b >= 64 && b <= 127)
+        return true; // 100.64.0.0/10 CGNAT
+    if (a === 198 && (b === 18 || b === 19))
+        return true; // 198.18.0.0/15 benchmarking
+    if (a === 255 && b === 255)
+        return true; // broadcast-ish
+    return false;
+}
+/**
+ * Expand an IPv6 literal into its 8 sixteen-bit groups, or null if unparseable.
+ * Handles `::` compression and an embedded IPv4 tail (`::ffff:127.0.0.1`).
+ */
+function parseIpv6(input) {
+    let s = input;
+    const tail = [];
+    // Peel off a trailing dotted-quad (IPv4-mapped/-compatible forms).
+    const v4 = /(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/.exec(s);
+    if (v4) {
+        const o = parseIpv4(v4[1]);
+        if (!o)
+            return null;
+        tail.push((o[0] << 8) | o[1], (o[2] << 8) | o[3]);
+        s = s.slice(0, v4.index); // leaves a trailing ':' before the compression split
+    }
+    const halves = s.split("::");
+    if (halves.length > 2)
+        return null; // more than one "::" is illegal
+    const head = halves[0] ? halves[0].split(":").filter(Boolean) : [];
+    const rest = halves[1] ? halves[1].split(":").filter(Boolean) : [];
+    const toNums = (groups) => {
+        const out = [];
+        for (const g of groups) {
+            if (!/^[0-9a-f]{1,4}$/.test(g))
+                return null;
+            out.push(parseInt(g, 16));
+        }
+        return out;
+    };
+    const headNums = toNums(head);
+    const restNums = toNums(rest);
+    if (!headNums || !restNums)
+        return null;
+    let groups;
+    if (halves.length === 2) {
+        const fill = 8 - (headNums.length + restNums.length + tail.length);
+        if (fill < 0)
+            return null;
+        groups = [
+            ...headNums,
+            ...Array(fill).fill(0),
+            ...restNums,
+            ...tail,
+        ];
+    }
+    else {
+        groups = [...headNums, ...tail];
+    }
+    return groups.length === 8 ? groups : null;
+}
+/** The dotted-quad embedded in an IPv6 tail's last two groups. */
+function embeddedV4(g) {
+    return `${g[6] >> 8}.${g[6] & 0xff}.${g[7] >> 8}.${g[7] & 0xff}`;
+}
+/** True if an expanded IPv6 address is in a range that must never be reached. */
+function isBlockedIpv6(g) {
+    // IPv4-mapped (::ffff:a.b.c.d) and IPv4-compatible (::a.b.c.d): check the v4 part.
+    const firstFiveZero = g.slice(0, 5).every((x) => x === 0);
+    const firstSixZero = firstFiveZero && g[5] === 0;
+    const embedded = embeddedV4(g);
+    if (firstFiveZero && g[5] === 0xffff)
+        return isBlockedIpv4(embedded); // ::ffff:x
+    if (firstSixZero &&
+        !(g[6] === 0 && g[7] === 0) &&
+        !(g[6] === 0 && g[7] === 1))
+        return isBlockedIpv4(embedded); // ::x.y.z.w (IPv4-compatible, deprecated)
+    if (g.every((x) => x === 0))
+        return true; // :: unspecified
+    if (firstSixZero && g[6] === 0 && g[7] === 1)
+        return true; // ::1 loopback
+    if ((g[0] & 0xffc0) === 0xfe80)
+        return true; // fe80::/10 link-local (fe80–febf)
+    if ((g[0] & 0xfe00) === 0xfc00)
+        return true; // fc00::/7 unique-local (fc00–fdff)
+    if ((g[0] & 0xff00) === 0xff00)
+        return true; // ff00::/8 multicast
+    return false;
+}
+/** Strip brackets, lowercase, and drop an IPv6 scope/zone id from an address. */
+function normalizeAddress(addr) {
+    return addr
+        .trim()
+        .toLowerCase()
+        .replace(/^\[|\]$/g, "")
+        .split("%")[0];
+}
+/** True if an address (v4 or v6) is in a range that must never be reached. */
+export function isBlockedAddress(addr) {
+    const ip = normalizeAddress(addr);
+    if (ip.includes(":")) {
+        const groups = parseIpv6(ip);
+        if (!groups)
+            return true; // fail closed: an unparseable colon-address is refused
+        return isBlockedIpv6(groups);
+    }
+    return isBlockedIpv4(ip);
+}
+/**
+ * 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 function isLoopbackAddress(addr) {
+    const ip = normalizeAddress(addr);
+    if (ip.includes(":")) {
+        const g = parseIpv6(ip);
+        if (!g)
+            return false;
+        const firstSixZero = g.slice(0, 6).every((x) => x === 0);
+        if (firstSixZero && g[6] === 0 && g[7] === 1)
+            return true; // ::1
+        // ::ffff:127.x and deprecated ::127.x embed a v4 loopback.
+        const firstFiveZero = g.slice(0, 5).every((x) => x === 0);
+        if (firstFiveZero && (g[5] === 0xffff || g[5] === 0)) {
+            const embedded = `${g[6] >> 8}.${g[6] & 0xff}.${g[7] >> 8}.${g[7] & 0xff}`;
+            const o = parseIpv4(embedded);
+            return o !== null && o[0] === 127;
+        }
+        return false;
+    }
+    const o = parseIpv4(ip);
+    return o !== null && o[0] === 127;
+}
+/**
+ * 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 async function assertAllPublic(host, resolve) {
+    const cleaned = host.replace(/^\[|\]$/g, "");
+    let addresses;
+    try {
+        addresses = await resolve(cleaned);
+    }
+    catch (err) {
+        throw new HostUnresolvedError(`could not resolve host "${cleaned}": ${err.message}`);
+    }
+    if (addresses.length === 0) {
+        throw new HostUnresolvedError(`host "${cleaned}" resolved to no addresses`);
+    }
+    for (const addr of addresses) {
+        if (isBlockedAddress(addr)) {
+            throw new BlockedHostError(`host "${cleaned}" resolves to ${addr}, a private/loopback/link-local address`);
+        }
+    }
+    return addresses;
+}
+/**
+ * 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 function pinnedLookup(addresses) {
+    const resolved = addresses.map((address) => ({
+        address,
+        family: address.includes(":") ? 6 : 4,
+    }));
+    return (_hostname, options, callback) => {
+        const all = typeof options === "object" && options !== null && "all" in options
+            ? options.all
+            : false;
+        if (all)
+            callback(null, resolved);
+        else
+            callback(null, resolved[0].address, resolved[0].family);
+    };
+}
+/** Sort + dedupe an address set so equality checks are order-insensitive. */
+export function normalizeAddressSet(addresses) {
+    return [...new Set(addresses.map(normalizeAddress))].sort();
+}

package/dist/render/capabilities.d.ts

@@ -1,4 +1,15 @@
 import type { RenderCapabilities, RenderStream } from "./types.js";
+/** Fallback width when the terminal reports none (non-TTY, pipe, unknown). */
+export declare const DEFAULT_COLUMNS = 80;
+/**
+ * Resolve the terminal width (U.12) — the single rule behind
+ * {@link RenderCapabilities.width} and every resize recompute. `COLUMNS` wins
+ * when set (honored so `COLUMNS=100 cruxy …` and CI overrides work), then the
+ * stream's own `columns`, then {@link DEFAULT_COLUMNS}. Never returns a
+ * non-positive width — an unknown terminal degrades to a sensible default, it
+ * does not crash a width calculation with 0.
+ */
+export declare function resolveColumns(stream?: RenderStream, env?: NodeJS.ProcessEnv): number;
 /**
  * Reduced-motion (U.11) — the ecosystem `NO_MOTION` signal, the explicit cruxy
  * knob `CRUXY_REDUCED_MOTION`, and `CRUXY_NO_SPINNER` kept as an alias flowing