@cruxy/cli 0.26.0 → 0.27.0

package/dist/config/schema.js

@@ -414,11 +414,17 @@ export const UsageConfigSchema = z
 })
     .strict();
 /**
- * One MCP server entry (C.27). A `command` (+ optional `args`/`env`) is a stdio
- * server cruxy spawns as a child process; a `url` names a remote server. Exactly
- * one transport must be given. Trusting a stdio server runs its code UNSANDBOXED
- * with your privileges, which is why connection is gated by an explicit,
- * fingerprinted trust decision (see `mcp/trust.ts`).
+ * One MCP server entry. A `command` (+ optional `args`/`env`) is a stdio server
+ * cruxy spawns as a child process (C.27); a `url` names a remote server reached
+ * over Streamable HTTP (C.27b). Exactly one transport must be given.
+ *
+ * Both are gated by an explicit, fingerprinted trust decision (`mcp/trust.ts`),
+ * but the escalation differs: a stdio server runs its code UNSANDBOXED with your
+ * privileges, while a `url` server runs remotely — cruxy sends it your tool
+ * arguments over the network (https + cert-validated + pinned to a public IP; http
+ * only for a loopback dev server) and treats its responses as untrusted data. A
+ * url's trust also binds its resolved IP set at trust time, so a later IP-set
+ * change re-gates (weaker than a local binary fingerprint — see `mcp/types.ts`).
  */
 export const McpServerSchema = z
     .object({
@@ -430,11 +436,43 @@ export const McpServerSchema = z
     env: z.record(z.string(), z.string()).default({}),
     /** Remote transport: the server URL (mutually exclusive with `command`). */
     url: z.string().url().optional(),
+    /**
+     * Remote auth (C.27c, url only): the NAME of a bearer credential, resolved
+     * solely from `~/.cruxy/credentials.json` (0600) as `Authorization: Bearer …`.
+     * This field holds a NAME, never the secret — a project config may name a
+     * credential it does not contain, so the value never lives in-repo. Resolution
+     * never consults the environment or any config file. Requires an `https` URL.
+     */
+    credentialRef: z.string().min(1).optional(),
+    /**
+     * Remote auth (C.27c, url only): raw request headers sent to the endpoint.
+     * A LIVE header value is a secret, so this is accepted ONLY from user-scope
+     * config (`~/.cruxy/config.json`) — the loader REJECTS it from project-scope
+     * config (a cloned repo must not inject live headers). Prefer `credentialRef`.
+     * Requires an `https` URL; reserved framing headers cannot be overridden.
+     */
+    headers: z.record(z.string(), z.string()).optional(),
 })
     .strict()
     .refine((s) => Boolean(s.command) !== Boolean(s.url), {
     message: "an MCP server needs exactly one of `command` (stdio) or `url`",
+})
+    .refine((s) => !((s.credentialRef || s.headers) && s.command), {
+    message: "`credentialRef`/`headers` are for `url` servers only (stdio auth uses `env`)",
+})
+    .refine((s) => !((s.credentialRef || s.headers) && s.url && !isHttps(s.url)), {
+    message: "a url server with `credentialRef`/`headers` must use https — a credential is " +
+        "NEVER sent over http (including loopback); there is no plaintext dev carve-out",
 });
+/** Whether a URL string parses as https (a credential is only ever sent over TLS). */
+function isHttps(url) {
+    try {
+        return new URL(url).protocol === "https:";
+    }
+    catch {
+        return false; // an invalid URL is rejected by `z.string().url()` upstream
+    }
+}
 /**
  * MCP client integration (C.27): connect to trusted MCP servers and expose their
  * tools to the agent. OFF by default — like the sandbox, LSP, and hooks, it runs

package/dist/errors/constructors.d.ts

@@ -303,6 +303,35 @@ export declare function mcpUntrusted(root: string, servers: string[]): CruxyErro
  * gag-scrubbed (U.8) before it reaches the user-facing cause.
  */
 export declare function mcpConnect(server: string, underlying?: unknown): CruxyError;
+/**
+ * A network (`url`) MCP server was REFUSED for a security reason (SSRF address
+ * block, a non-https/non-loopback scheme, or an endpoint redirect) — distinct
+ * from a transient connect failure. `reason` is our own guard's message (not
+ * server-controlled), but it is still scrubbed for symmetry with `mcpConnect`.
+ */
+export declare function mcpBlocked(server: string, reason: string): CruxyError;
+/**
+ * A network (`url`) MCP server's CREDENTIAL failed (C.27c) — either the endpoint
+ * REJECTED it (401/403) or the configured `credentialRef` names no token in the
+ * `~/.cruxy` store. Distinct from `mcpConnect` (the server was reachable) and from
+ * `mcpBlocked` (a security refusal before connect). The token is NEVER included in
+ * this error — only the server name and the credential NAME appear.
+ */
+export declare function mcpAuth(server: string, detail: {
+    kind: "rejected";
+    status: number;
+} | {
+    kind: "missing";
+    ref: string;
+}): CruxyError;
+/**
+ * A project-scope config tried to set raw `headers` on an MCP server (C.27c). A
+ * live header value is a secret, and project scope is a possibly-cloned repo, so
+ * this is REFUSED at load — never silently dropped (a silent drop would let a repo
+ * believe auth is configured when it is not). The repo may only NAME a credential
+ * via `credentialRef`; the value lives solely in the user's `~/.cruxy` store.
+ */
+export declare function mcpProjectHeaders(server: string, file: string): CruxyError;
 /**
  * `web.enabled` is on but no usable search provider is configured — the API-key
  * environment variable is unset (or the provider is unknown). THE HONESTY RULE:

package/dist/errors/constructors.js

@@ -1034,6 +1034,75 @@ export function mcpConnect(server, underlying) {
         underlying,
     });
 }
+/**
+ * A network (`url`) MCP server was REFUSED for a security reason (SSRF address
+ * block, a non-https/non-loopback scheme, or an endpoint redirect) — distinct
+ * from a transient connect failure. `reason` is our own guard's message (not
+ * server-controlled), but it is still scrubbed for symmetry with `mcpConnect`.
+ */
+export function mcpBlocked(server, reason) {
+    return new CruxyError({
+        code: ErrorCode.McpBlocked,
+        title: `refused to connect to MCP server "${server}"`,
+        cause: reason,
+        nextSteps: [
+            "use an `https://` URL that resolves to a public address",
+            "for a local dev server use `http://` to a loopback host, or a `command` (stdio) server",
+        ],
+        meta: { server },
+    });
+}
+/**
+ * A network (`url`) MCP server's CREDENTIAL failed (C.27c) — either the endpoint
+ * REJECTED it (401/403) or the configured `credentialRef` names no token in the
+ * `~/.cruxy` store. Distinct from `mcpConnect` (the server was reachable) and from
+ * `mcpBlocked` (a security refusal before connect). The token is NEVER included in
+ * this error — only the server name and the credential NAME appear.
+ */
+export function mcpAuth(server, detail) {
+    if (detail.kind === "rejected") {
+        return new CruxyError({
+            code: ErrorCode.McpAuth,
+            title: `credential for MCP server "${server}" was rejected`,
+            cause: `the endpoint returned ${detail.status} — the bearer credential is missing, wrong, or expired`,
+            nextSteps: [
+                `check the credential in \`~/.cruxy/credentials.json\` and re-set it with \`cruxy mcp login ${server}\``,
+                "confirm the token is still valid on the server side",
+            ],
+            meta: { server, status: detail.status },
+        });
+    }
+    return new CruxyError({
+        code: ErrorCode.McpAuth,
+        title: `MCP server "${server}" needs a credential that is not set`,
+        cause: `no credential named "${detail.ref}" was found in \`~/.cruxy/credentials.json\``,
+        nextSteps: [
+            `set it with \`cruxy mcp login ${server}\` (stored owner-only in ~/.cruxy)`,
+            "the token is never read from the repo, config, or the environment",
+        ],
+        meta: { server, credentialRef: detail.ref },
+    });
+}
+/**
+ * A project-scope config tried to set raw `headers` on an MCP server (C.27c). A
+ * live header value is a secret, and project scope is a possibly-cloned repo, so
+ * this is REFUSED at load — never silently dropped (a silent drop would let a repo
+ * believe auth is configured when it is not). The repo may only NAME a credential
+ * via `credentialRef`; the value lives solely in the user's `~/.cruxy` store.
+ */
+export function mcpProjectHeaders(server, file) {
+    return new CruxyError({
+        code: ErrorCode.McpConfig,
+        title: `raw MCP \`headers\` are not allowed in project config`,
+        cause: `server "${server}" in ${file} sets \`headers\` directly — a live header value ` +
+            "is a secret, and a project config (a possibly-cloned repo) must never carry one",
+        nextSteps: [
+            `remove \`headers\` from server "${server}" and use \`credentialRef: "<name>"\` instead`,
+            `store the token with \`cruxy mcp login ${server}\`, or set raw \`headers\` only in \`~/.cruxy/config.json\``,
+        ],
+        meta: { server, file },
+    });
+}
 // ── web search + fetch (exit 17) — C.20 ───────────────────────────────────────
 /**
  * `web.enabled` is on but no usable search provider is configured — the API-key

package/dist/errors/types.d.ts

@@ -110,6 +110,21 @@ export declare const ErrorCode: {
      * or list its tools. Surfaced (that server contributes no tools) rather than
      * silently swallowed; never fatal to the run. */
     readonly McpConnect: "CRUXY_E_MCP_CONNECT";
+    /** A network (`url`) MCP server was REFUSED before/at connect for a SECURITY
+     * reason, distinct from an ordinary connect failure: a non-https(non-loopback)
+     * scheme, a host that resolves into a private/loopback/link-local range (SSRF),
+     * or an endpoint that tried to redirect. A refusal, not a transient error. */
+    readonly McpBlocked: "CRUXY_E_MCP_BLOCKED";
+    /** A network (`url`) MCP server's CREDENTIAL failed (C.27c): the endpoint
+     * rejected it (401/403) or the named `credentialRef` has no token in the
+     * `~/.cruxy` store. Distinct from a transport connect failure — the server was
+     * reached (or the credential was simply absent), not merely unreachable. */
+    readonly McpAuth: "CRUXY_E_MCP_AUTH";
+    /** A project-scope config was REFUSED for a credential-safety reason (C.27c):
+     * it tried to set raw `headers` on an MCP server. A live header value is a
+     * secret; project scope (a possibly-cloned repo) may only NAME a credential via
+     * `credentialRef`, never carry the value. Rejected loudly, never silently. */
+    readonly McpConfig: "CRUXY_E_MCP_CONFIG";
     /** `web.enabled` is on but no usable search provider is configured — the API
      * key env var is unset or the provider is unknown. Actionable, NEVER a silent
      * empty result: "no provider" must not read as "no search results". */

package/dist/errors/types.js

@@ -128,6 +128,21 @@ export const ErrorCode = {
      * or list its tools. Surfaced (that server contributes no tools) rather than
      * silently swallowed; never fatal to the run. */
     McpConnect: "CRUXY_E_MCP_CONNECT",
+    /** A network (`url`) MCP server was REFUSED before/at connect for a SECURITY
+     * reason, distinct from an ordinary connect failure: a non-https(non-loopback)
+     * scheme, a host that resolves into a private/loopback/link-local range (SSRF),
+     * or an endpoint that tried to redirect. A refusal, not a transient error. */
+    McpBlocked: "CRUXY_E_MCP_BLOCKED",
+    /** A network (`url`) MCP server's CREDENTIAL failed (C.27c): the endpoint
+     * rejected it (401/403) or the named `credentialRef` has no token in the
+     * `~/.cruxy` store. Distinct from a transport connect failure — the server was
+     * reached (or the credential was simply absent), not merely unreachable. */
+    McpAuth: "CRUXY_E_MCP_AUTH",
+    /** A project-scope config was REFUSED for a credential-safety reason (C.27c):
+     * it tried to set raw `headers` on an MCP server. A live header value is a
+     * secret; project scope (a possibly-cloned repo) may only NAME a credential via
+     * `credentialRef`, never carry the value. Rejected loudly, never silently. */
+    McpConfig: "CRUXY_E_MCP_CONFIG",
     // web search + fetch (exit 17) — C.20
     /** `web.enabled` is on but no usable search provider is configured — the API
      * key env var is unset or the provider is unknown. Actionable, NEVER a silent
@@ -293,6 +308,9 @@ const EXIT_CODES = {
     // never fatal on its own. Grouped for a greppable exit code.
     [ErrorCode.McpUntrusted]: 16,
     [ErrorCode.McpConnect]: 16,
+    [ErrorCode.McpBlocked]: 16,
+    [ErrorCode.McpAuth]: 16,
+    [ErrorCode.McpConfig]: 16,
     // Web search + fetch (C.20). A missing provider, a search/fetch failure, and an
     // SSRF-blocked host all surface inside a tool result (the agent reads and
     // adapts) and only exit the process if thrown directly. Grouped for a greppable

package/dist/mcp/http-transport.d.ts

@@ -0,0 +1,89 @@
+import { fetch as undiciFetch } from "undici";
+import type { McpTransport } from "./types.js";
+/**
+ * JSON-RPC 2.0 over MCP's Streamable HTTP transport (C.27b) — the network sibling
+ * of {@link ../mcp/transport McpStdioTransport}. It satisfies the SAME
+ * {@link McpTransport} seam, so `McpClient`, the single adapter (`mcpToolsFrom`),
+ * bounds, demarcation, gating, and non-persistence are all inherited UNCHANGED —
+ * every C.27 security property holds over the wire by construction, and all the
+ * network-specific hardening lives here, below the seam.
+ *
+ * Trust boundary (this is a remote endpoint, not a local process):
+ * - PINNED CONNECTIONS. The connection is pinned (undici `Agent` + {@link pinnedLookup})
+ *   to the exact address set the SSRF guard already validated at trust time. The
+ *   transport itself does NO DNS resolution — it dials only the passed addresses,
+ *   so a DNS rebind cannot flip check→connect. The Host header / TLS SNI still
+ *   carry the original hostname, so certificate hostname validation is unaffected.
+ * - HTTPS + CERT VALIDATION. TLS validation is undici's default and is NEVER
+ *   disabled — there is deliberately no skip-verify path (JC-E). `https` vs
+ *   loopback-`http` is enforced upstream by the url-guard.
+ * - NO REDIRECTS. `maxRedirections: 0` and a manual 3xx check: an MCP RPC endpoint
+ *   has no legitimate reason to redirect, so a redirect is REFUSED (never re-pinned
+ *   and followed to a new, unvalidated host).
+ * - NO SOCKET BEFORE TRUST (JC-C). The constructor opens no socket and resolves no
+ *   DNS; the first network I/O is the `initialize` POST, which the service issues
+ *   only after the trust gate passes.
+ *
+ * Inbound posture mirrors stdio: cruxy advertises NO capabilities (no sampling, no
+ * roots, no elicitation), so it never solicits server→client requests; any that
+ * arrive on a response stream are ignored, never acted on. This is a deliberate
+ * SUBSET of Streamable HTTP — no standalone GET listening stream and no SSE
+ * resumption — sufficient for request/response tool use and easy to reason about.
+ */
+export interface McpHttpSpec {
+    /** The server endpoint (already scheme/SSRF-validated by the url-guard). */
+    url: string;
+    /** Pre-validated address set to pin the connection to (never re-resolved here). */
+    addresses: string[];
+    /** `initialize` + `tools/list` budget, ms. */
+    connectTimeout: number;
+    /** Per `tools/call` budget, ms. */
+    requestTimeout: number;
+    /**
+     * Resolved auth headers (C.27c), attached to every request to THIS pinned,
+     * https endpoint (never on a redirect target, never over http). Empty/absent for
+     * an unauthenticated server. Reserved framing headers here are ignored — a
+     * credential can never rewrite content-type/accept/session framing.
+     */
+    authHeaders?: Record<string, string>;
+}
+/**
+ * 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 declare class McpHttpAuthError extends Error {
+    readonly status: number;
+    constructor(status: number);
+}
+/** Minimal fetch surface we depend on (injectable for tests). */
+type FetchLike = typeof undiciFetch;
+export declare class McpHttpTransport implements McpTransport {
+    private readonly url;
+    private readonly connectTimeout;
+    private readonly requestTimeout;
+    private readonly dispatcher;
+    private readonly fetchImpl;
+    /** Sanitized auth headers, sent ONLY over https to this pinned endpoint. */
+    private readonly authHeaders;
+    private nextId;
+    private disposed;
+    /** Streamable HTTP session id, captured from the `initialize` response. */
+    private sessionId;
+    private crashHandler;
+    /** In-flight request aborts, so `dispose()` can cancel them. */
+    private readonly inflight;
+    constructor(spec: McpHttpSpec, fetchImpl?: FetchLike);
+    /** Whether the `initialize` handshake budget or the per-call budget applies. */
+    private budgetFor;
+    request(method: string, params: unknown, timeoutMs: number): Promise<unknown>;
+    notify(method: string, params: unknown): void;
+    onCrash(handler: (info: {
+        code: number | null;
+        signal: string | null;
+    }) => void): void;
+    dispose(): Promise<void>;
+    /** POST one framed JSON-RPC message; refuse redirects; reject non-2xx. */
+    private post;
+}
+export {};

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