@cruxy/cli 0.25.0 → 0.27.0

package/dist/config/schema.d.ts

@@ -649,13 +649,19 @@ export declare const UsageConfigSchema: z.ZodObject<{
 }>;
 export type UsageConfig = z.infer<typeof UsageConfigSchema>;
 /**
- * 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 declare const McpServerSchema: z.ZodEffects<z.ZodObject<{
+export declare const McpServerSchema: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodObject<{
     /** stdio transport: the server program to spawn. */
     command: z.ZodOptional<z.ZodString>;
     /** Arguments for `command`. */
@@ -664,26 +670,78 @@ export declare const McpServerSchema: z.ZodEffects<z.ZodObject<{
     env: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
     /** Remote transport: the server URL (mutually exclusive with `command`). */
     url: z.ZodOptional<z.ZodString>;
+    /**
+     * 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.ZodOptional<z.ZodString>;
+    /**
+     * 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.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
 }, "strict", z.ZodTypeAny, {
     args: string[];
     env: Record<string, string>;
     command?: string | undefined;
+    credentialRef?: string | undefined;
+    url?: string | undefined;
+    headers?: Record<string, string> | undefined;
+}, {
+    command?: string | undefined;
+    credentialRef?: string | undefined;
+    url?: string | undefined;
+    args?: string[] | undefined;
+    env?: Record<string, string> | undefined;
+    headers?: Record<string, string> | undefined;
+}>, {
+    args: string[];
+    env: Record<string, string>;
+    command?: string | undefined;
+    credentialRef?: string | undefined;
     url?: string | undefined;
+    headers?: Record<string, string> | undefined;
 }, {
     command?: string | undefined;
+    credentialRef?: string | undefined;
     url?: string | undefined;
     args?: string[] | undefined;
     env?: Record<string, string> | undefined;
+    headers?: Record<string, string> | undefined;
 }>, {
     args: string[];
     env: Record<string, string>;
     command?: string | undefined;
+    credentialRef?: string | undefined;
     url?: string | undefined;
+    headers?: Record<string, string> | undefined;
 }, {
     command?: string | undefined;
+    credentialRef?: string | undefined;
     url?: string | undefined;
     args?: string[] | undefined;
     env?: Record<string, string> | undefined;
+    headers?: Record<string, string> | undefined;
+}>, {
+    args: string[];
+    env: Record<string, string>;
+    command?: string | undefined;
+    credentialRef?: string | undefined;
+    url?: string | undefined;
+    headers?: Record<string, string> | undefined;
+}, {
+    command?: string | undefined;
+    credentialRef?: string | undefined;
+    url?: string | undefined;
+    args?: string[] | undefined;
+    env?: Record<string, string> | undefined;
+    headers?: Record<string, string> | undefined;
 }>;
 export type McpServerConfig = z.infer<typeof McpServerSchema>;
 /**
@@ -704,7 +762,7 @@ export declare const McpConfigSchema: z.ZodObject<{
     enabled: z.ZodDefault<z.ZodBoolean>;
     /** Named MCP servers, keyed by a short server id used as the tool prefix
      * (`mcp__<server>__<tool>`) and in the trust prompt. */
-    servers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodObject<{
+    servers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodObject<{
         /** stdio transport: the server program to spawn. */
         command: z.ZodOptional<z.ZodString>;
         /** Arguments for `command`. */
@@ -713,26 +771,78 @@ export declare const McpConfigSchema: z.ZodObject<{
         env: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
         /** Remote transport: the server URL (mutually exclusive with `command`). */
         url: z.ZodOptional<z.ZodString>;
+        /**
+         * 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.ZodOptional<z.ZodString>;
+        /**
+         * 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.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     }, "strict", z.ZodTypeAny, {
         args: string[];
         env: Record<string, string>;
         command?: string | undefined;
+        credentialRef?: string | undefined;
         url?: string | undefined;
+        headers?: Record<string, string> | undefined;
     }, {
         command?: string | undefined;
+        credentialRef?: string | undefined;
         url?: string | undefined;
         args?: string[] | undefined;
         env?: Record<string, string> | undefined;
+        headers?: Record<string, string> | undefined;
     }>, {
         args: string[];
         env: Record<string, string>;
         command?: string | undefined;
+        credentialRef?: string | undefined;
         url?: string | undefined;
+        headers?: Record<string, string> | undefined;
     }, {
         command?: string | undefined;
+        credentialRef?: string | undefined;
         url?: string | undefined;
         args?: string[] | undefined;
         env?: Record<string, string> | undefined;
+        headers?: Record<string, string> | undefined;
+    }>, {
+        args: string[];
+        env: Record<string, string>;
+        command?: string | undefined;
+        credentialRef?: string | undefined;
+        url?: string | undefined;
+        headers?: Record<string, string> | undefined;
+    }, {
+        command?: string | undefined;
+        credentialRef?: string | undefined;
+        url?: string | undefined;
+        args?: string[] | undefined;
+        env?: Record<string, string> | undefined;
+        headers?: Record<string, string> | undefined;
+    }>, {
+        args: string[];
+        env: Record<string, string>;
+        command?: string | undefined;
+        credentialRef?: string | undefined;
+        url?: string | undefined;
+        headers?: Record<string, string> | undefined;
+    }, {
+        command?: string | undefined;
+        credentialRef?: string | undefined;
+        url?: string | undefined;
+        args?: string[] | undefined;
+        env?: Record<string, string> | undefined;
+        headers?: Record<string, string> | undefined;
     }>>>;
     /** Fail a server's `initialize` handshake (its tools are skipped) if it does
      * not complete within this many ms. */
@@ -756,7 +866,9 @@ export declare const McpConfigSchema: z.ZodObject<{
         args: string[];
         env: Record<string, string>;
         command?: string | undefined;
+        credentialRef?: string | undefined;
         url?: string | undefined;
+        headers?: Record<string, string> | undefined;
     }>;
     enabled: boolean;
     maxToolsPerServer: number;
@@ -767,9 +879,11 @@ export declare const McpConfigSchema: z.ZodObject<{
     requestTimeout?: number | undefined;
     servers?: Record<string, {
         command?: string | undefined;
+        credentialRef?: string | undefined;
         url?: string | undefined;
         args?: string[] | undefined;
         env?: Record<string, string> | undefined;
+        headers?: Record<string, string> | undefined;
     }> | undefined;
     enabled?: boolean | undefined;
     maxToolsPerServer?: number | undefined;
@@ -1380,7 +1494,7 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
         /** Named MCP servers, keyed by a short server id used as the tool prefix
          * (`mcp__<server>__<tool>`) and in the trust prompt. */
-        servers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodObject<{
+        servers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodObject<{
             /** stdio transport: the server program to spawn. */
             command: z.ZodOptional<z.ZodString>;
             /** Arguments for `command`. */
@@ -1389,26 +1503,78 @@ export declare const CruxyConfigSchema: z.ZodObject<{
             env: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
             /** Remote transport: the server URL (mutually exclusive with `command`). */
             url: z.ZodOptional<z.ZodString>;
+            /**
+             * 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.ZodOptional<z.ZodString>;
+            /**
+             * 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.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         }, "strict", z.ZodTypeAny, {
             args: string[];
             env: Record<string, string>;
             command?: string | undefined;
+            credentialRef?: string | undefined;
+            url?: string | undefined;
+            headers?: Record<string, string> | undefined;
+        }, {
+            command?: string | undefined;
+            credentialRef?: string | undefined;
+            url?: string | undefined;
+            args?: string[] | undefined;
+            env?: Record<string, string> | undefined;
+            headers?: Record<string, string> | undefined;
+        }>, {
+            args: string[];
+            env: Record<string, string>;
+            command?: string | undefined;
+            credentialRef?: string | undefined;
+            url?: string | undefined;
+            headers?: Record<string, string> | undefined;
+        }, {
+            command?: string | undefined;
+            credentialRef?: string | undefined;
+            url?: string | undefined;
+            args?: string[] | undefined;
+            env?: Record<string, string> | undefined;
+            headers?: Record<string, string> | undefined;
+        }>, {
+            args: string[];
+            env: Record<string, string>;
+            command?: string | undefined;
+            credentialRef?: string | undefined;
             url?: string | undefined;
+            headers?: Record<string, string> | undefined;
         }, {
             command?: string | undefined;
+            credentialRef?: string | undefined;
             url?: string | undefined;
             args?: string[] | undefined;
             env?: Record<string, string> | undefined;
+            headers?: Record<string, string> | undefined;
         }>, {
             args: string[];
             env: Record<string, string>;
             command?: string | undefined;
+            credentialRef?: string | undefined;
             url?: string | undefined;
+            headers?: Record<string, string> | undefined;
         }, {
             command?: string | undefined;
+            credentialRef?: string | undefined;
             url?: string | undefined;
             args?: string[] | undefined;
             env?: Record<string, string> | undefined;
+            headers?: Record<string, string> | undefined;
         }>>>;
         /** Fail a server's `initialize` handshake (its tools are skipped) if it does
          * not complete within this many ms. */
@@ -1432,7 +1598,9 @@ export declare const CruxyConfigSchema: z.ZodObject<{
             args: string[];
             env: Record<string, string>;
             command?: string | undefined;
+            credentialRef?: string | undefined;
             url?: string | undefined;
+            headers?: Record<string, string> | undefined;
         }>;
         enabled: boolean;
         maxToolsPerServer: number;
@@ -1443,9 +1611,11 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         requestTimeout?: number | undefined;
         servers?: Record<string, {
             command?: string | undefined;
+            credentialRef?: string | undefined;
             url?: string | undefined;
             args?: string[] | undefined;
             env?: Record<string, string> | undefined;
+            headers?: Record<string, string> | undefined;
         }> | undefined;
         enabled?: boolean | undefined;
         maxToolsPerServer?: number | undefined;
@@ -1633,7 +1803,9 @@ export declare const CruxyConfigSchema: z.ZodObject<{
             args: string[];
             env: Record<string, string>;
             command?: string | undefined;
+            credentialRef?: string | undefined;
             url?: string | undefined;
+            headers?: Record<string, string> | undefined;
         }>;
         enabled: boolean;
         maxToolsPerServer: number;
@@ -1781,9 +1953,11 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         requestTimeout?: number | undefined;
         servers?: Record<string, {
             command?: string | undefined;
+            credentialRef?: string | undefined;
             url?: string | undefined;
             args?: string[] | undefined;
             env?: Record<string, string> | undefined;
+            headers?: Record<string, string> | undefined;
         }> | undefined;
         enabled?: boolean | undefined;
         maxToolsPerServer?: number | undefined;

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