codex-plugin-doctor 1.51.0 → 1.53.0

package/dist/core/remote-mcp-probe.js

@@ -0,0 +1,284 @@
+import { BoundedHttpError, requestBoundedHttp } from "./bounded-http-client.js";
+import { RemoteNetworkPolicyError } from "./remote-network-policy.js";
+import { checkRemoteOAuthReadiness } from "./remote-oauth-readiness.js";
+import { probeRemoteTransportReliability } from "./remote-transport-reliability.js";
+import { inspectRemoteMcpUrl } from "./remote-url-policy.js";
+import { packageVersion } from "../version.js";
+const MCP_PROTOCOL_VERSION = "2025-11-25";
+function createScorecard() {
+    return {
+        transport: "skipped",
+        networkSafety: "skipped",
+        initialize: "skipped",
+        contentType: "skipped",
+        session: "absent",
+        protocolHeaders: "skipped",
+        authorization: "skipped",
+        overall: "skipped"
+    };
+}
+function failure(id, message, impact, suggestedFix) {
+    return { id, severity: "fail", message, impact, suggestedFix };
+}
+function finalize(scorecard, findings) {
+    scorecard.overall = findings.some((finding) => finding.severity === "fail")
+        ? "fail"
+        : findings.some((finding) => finding.severity === "warn")
+            ? "warn"
+            : scorecard.initialize === "pass" || scorecard.authorization === "pass"
+                ? "pass"
+                : "skipped";
+    return { findings, scorecard };
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function responseHeader(headers, name) {
+    const value = headers[name];
+    return typeof value === "string" ? value : null;
+}
+function mediaType(value) {
+    return value?.split(";", 1)[0]?.trim().toLowerCase() ?? null;
+}
+function parseJsonObject(source) {
+    try {
+        const parsed = JSON.parse(source);
+        return isPlainObject(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function isInitializeResponseCandidate(message) {
+    return message.id === 1;
+}
+function findSseInitializeResponse(body) {
+    const text = body.toString("utf8").replace(/\r\n/g, "\n");
+    let offset = 0;
+    while (offset < text.length) {
+        const boundary = text.indexOf("\n\n", offset);
+        if (boundary === -1) {
+            return null;
+        }
+        const data = text.slice(offset, boundary).split("\n")
+            .filter((line) => line.startsWith("data:"))
+            .map((line) => line.slice(5).replace(/^ /, ""));
+        const message = data.length > 0 ? parseJsonObject(data.join("\n")) : null;
+        if (message && isInitializeResponseCandidate(message)) {
+            return message;
+        }
+        offset = boundary + 2;
+    }
+    return null;
+}
+function parseInitializeResponse(body, contentType) {
+    return contentType === "text/event-stream"
+        ? findSseInitializeResponse(body)
+        : parseJsonObject(body.toString("utf8"));
+}
+function isValidInitializeResponse(message) {
+    return (message.jsonrpc === "2.0" &&
+        message.id === 1 &&
+        isPlainObject(message.result) &&
+        message.result.protocolVersion === MCP_PROTOCOL_VERSION &&
+        isPlainObject(message.result.capabilities) &&
+        isPlainObject(message.result.serverInfo) &&
+        typeof message.result.serverInfo.name === "string" &&
+        typeof message.result.serverInfo.version === "string");
+}
+function isInitializedNotificationAcknowledged(response) {
+    return response.statusCode === 202 && response.body.length === 0;
+}
+function validSessionId(value) {
+    return value !== null && /^[\x21-\x7e]+$/.test(value);
+}
+function transportFailureId(error) {
+    if (error instanceof BoundedHttpError) {
+        if (error.code === "REMOTE_HTTP_TIMEOUT")
+            return "plugin.runtime.remote.transport.timeout";
+        if (error.code === "REMOTE_HTTP_RESPONSE_TOO_LARGE")
+            return "plugin.runtime.remote.transport.response_too_large";
+    }
+    return "plugin.runtime.remote.transport.failed";
+}
+function transportStatus(error) {
+    return error instanceof RemoteNetworkPolicyError
+        ? "skipped"
+        : "fail";
+}
+export async function probeRemoteMcpServer(serverName, rawUrl, options = {}) {
+    const scorecard = createScorecard();
+    const findings = [];
+    const request = options.request ?? requestBoundedHttp;
+    if (!options.allowNetwork) {
+        scorecard.networkSafety = "fail";
+        findings.push(failure("plugin.runtime.remote.network_not_approved", `The remote MCP server \`${serverName}\` was not contacted because network probing is not approved.`, "Remote MCP initialization can create outbound network traffic and must be explicitly approved.", "Enable remote network probing only after reviewing the server endpoint."));
+        return finalize(scorecard, findings);
+    }
+    const inspection = inspectRemoteMcpUrl(rawUrl);
+    if (inspection.issues.length > 0) {
+        scorecard.networkSafety = "fail";
+        findings.push(failure("plugin.runtime.remote.url.invalid", `The remote MCP server \`${serverName}\` has an unsafe or unsupported endpoint URL.`, "Unsafe remote endpoint URLs can bypass network controls or expose credentials.", "Use an absolute HTTP or HTTPS endpoint without credentials, query parameters, fragments, or IP literals."));
+        return finalize(scorecard, findings);
+    }
+    scorecard.networkSafety = "pass";
+    const initializeBody = JSON.stringify({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "initialize",
+        params: {
+            protocolVersion: MCP_PROTOCOL_VERSION,
+            capabilities: {},
+            clientInfo: { name: "Codex Plugin Doctor", version: packageVersion }
+        }
+    });
+    let initializeResponse;
+    try {
+        initializeResponse = await request(rawUrl, {
+            allowLocalNetwork: options.allowLocalNetwork,
+            lookup: options.lookup,
+            timeoutMs: options.requestTimeoutMs,
+            method: "POST",
+            body: initializeBody,
+            headers: {
+                Accept: "application/json, text/event-stream",
+                "Content-Type": "application/json"
+            },
+            stopAfter: (body) => findSseInitializeResponse(body) !== null
+        });
+    }
+    catch (error) {
+        scorecard.transport = transportStatus(error);
+        if (error instanceof RemoteNetworkPolicyError) {
+            scorecard.networkSafety = "fail";
+        }
+        findings.push(failure(transportFailureId(error), `The remote MCP server \`${serverName}\` could not complete a bounded initialize request.`, "A failed transport prevents safe MCP protocol negotiation.", "Verify the endpoint is reachable and complies with the configured remote network policy."));
+        return finalize(scorecard, findings);
+    }
+    scorecard.transport = "pass";
+    if (initializeResponse.statusCode === 401) {
+        const challenge = initializeResponse.headers["www-authenticate"];
+        const readiness = await checkRemoteOAuthReadiness(inspection.sanitizedUrl ?? rawUrl, challenge === undefined ? [] : [challenge], {
+            request,
+            requestOptions: {
+                allowLocalNetwork: options.allowLocalNetwork,
+                lookup: options.lookup,
+                timeoutMs: options.requestTimeoutMs
+            }
+        });
+        scorecard.authorization = readiness.status;
+        findings.push(...readiness.findings);
+        return finalize(scorecard, findings);
+    }
+    if (initializeResponse.statusCode !== 200) {
+        scorecard.initialize = "fail";
+        findings.push(failure("plugin.runtime.remote.http_status.invalid", `The remote MCP server \`${serverName}\` returned an unexpected initialize HTTP status.`, "Streamable HTTP MCP initialization requires a successful response before protocol negotiation can continue.", "Return HTTP 200 for initialize, or configure authorization before probing a protected endpoint."));
+        return finalize(scorecard, findings);
+    }
+    const contentType = mediaType(responseHeader(initializeResponse.headers, "content-type"));
+    if (contentType !== "application/json" && contentType !== "text/event-stream") {
+        scorecard.contentType = "fail";
+        scorecard.initialize = "fail";
+        findings.push(failure("plugin.runtime.remote.content_type.invalid", `The remote MCP server \`${serverName}\` returned an unsupported initialize content type.`, "MCP initialization responses must be JSON or Server-Sent Events so the JSON-RPC result can be validated.", "Return application/json or text/event-stream with a JSON-RPC initialize response."));
+        return finalize(scorecard, findings);
+    }
+    scorecard.contentType = "pass";
+    const sessionId = responseHeader(initializeResponse.headers, "mcp-session-id");
+    if (sessionId !== null && !validSessionId(sessionId)) {
+        scorecard.session = "present-invalid";
+        scorecard.initialize = "fail";
+        findings.push(failure("plugin.runtime.remote.session.invalid", `The remote MCP server \`${serverName}\` returned an invalid MCP session header.`, "Invalid session identifiers cannot be safely replayed on the initialized notification.", "Return MCP-Session-Id only as visible ASCII characters."));
+        return finalize(scorecard, findings);
+    }
+    if (sessionId !== null) {
+        scorecard.session = "present-valid";
+    }
+    const initializeMessage = parseInitializeResponse(initializeResponse.body, contentType);
+    if (!initializeMessage || !isValidInitializeResponse(initializeMessage)) {
+        scorecard.initialize = "fail";
+        findings.push(failure("plugin.runtime.remote.initialize.invalid", `The remote MCP server \`${serverName}\` returned an invalid initialize JSON-RPC result.`, "A malformed initialize result prevents protocol version negotiation.", "Return a JSON-RPC 2.0 result with id 1 and protocol version 2025-11-25."));
+        return finalize(scorecard, findings);
+    }
+    scorecard.initialize = "pass";
+    try {
+        const initializedResponse = await request(rawUrl, {
+            allowLocalNetwork: options.allowLocalNetwork,
+            lookup: options.lookup,
+            timeoutMs: options.requestTimeoutMs,
+            method: "POST",
+            body: JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" }),
+            headers: {
+                Accept: "application/json, text/event-stream",
+                "Content-Type": "application/json",
+                "MCP-Protocol-Version": MCP_PROTOCOL_VERSION,
+                ...(sessionId === null ? {} : { "MCP-Session-Id": sessionId })
+            }
+        });
+        if (!isInitializedNotificationAcknowledged(initializedResponse)) {
+            scorecard.protocolHeaders = "fail";
+            findings.push(failure("plugin.runtime.remote.initialized.failed", `The remote MCP server \`${serverName}\` did not acknowledge the initialized notification.`, "The MCP session may not be ready for subsequent protocol traffic.", "Accept a successful HTTP response to notifications/initialized at the same MCP endpoint."));
+            return finalize(scorecard, findings);
+        }
+    }
+    catch {
+        scorecard.protocolHeaders = "fail";
+        findings.push(failure("plugin.runtime.remote.initialized.failed", `The remote MCP server \`${serverName}\` could not receive the initialized notification.`, "The MCP session may not be ready for subsequent protocol traffic.", "Accept a successful HTTP response to notifications/initialized at the same MCP endpoint."));
+        return finalize(scorecard, findings);
+    }
+    scorecard.protocolHeaders = "pass";
+    const reliability = await probeRemoteTransportReliability({
+        rawUrl,
+        protocolVersion: MCP_PROTOCOL_VERSION,
+        request,
+        requestTimeoutMs: options.requestTimeoutMs,
+        requestOptions: {
+            allowLocalNetwork: options.allowLocalNetwork,
+            lookup: options.lookup
+        },
+        sessionId,
+        allowSessionLifecycle: options.allowSessionLifecycle,
+        reinitialize: async (requestWithinBudget) => {
+            const restartInitialize = await requestWithinBudget({
+                method: "POST",
+                body: initializeBody,
+                headers: {
+                    Accept: "application/json, text/event-stream",
+                    "Content-Type": "application/json"
+                },
+                stopAfter: (body) => findSseInitializeResponse(body) !== null
+            });
+            if (restartInitialize.statusCode !== 200) {
+                throw new Error("restart initialize failed");
+            }
+            const restartContentType = mediaType(responseHeader(restartInitialize.headers, "content-type"));
+            if (restartContentType !== "application/json" && restartContentType !== "text/event-stream") {
+                throw new Error("restart initialize content type invalid");
+            }
+            const replacementSessionId = responseHeader(restartInitialize.headers, "mcp-session-id");
+            if (replacementSessionId !== null && !validSessionId(replacementSessionId)) {
+                throw new Error("restart session invalid");
+            }
+            const restartMessage = parseInitializeResponse(restartInitialize.body, restartContentType);
+            if (!restartMessage || !isValidInitializeResponse(restartMessage)) {
+                throw new Error("restart initialize result invalid");
+            }
+            const restartInitialized = await requestWithinBudget({
+                method: "POST",
+                body: JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" }),
+                headers: {
+                    Accept: "application/json, text/event-stream",
+                    "Content-Type": "application/json",
+                    "MCP-Protocol-Version": MCP_PROTOCOL_VERSION,
+                    ...(replacementSessionId === null ? {} : { "MCP-Session-Id": replacementSessionId })
+                }
+            });
+            if (!isInitializedNotificationAcknowledged(restartInitialized)) {
+                throw new Error("restart initialized failed");
+            }
+            return replacementSessionId;
+        }
+    });
+    scorecard.reliability = reliability.scorecard;
+    findings.push(...reliability.findings);
+    return finalize(scorecard, findings);
+}

package/dist/core/remote-network-policy.d.ts

@@ -0,0 +1,24 @@
+export interface ResolvedRemoteTarget {
+    hostname: string;
+    address: string;
+    family: 4 | 6;
+    local: boolean;
+}
+export interface RemoteLookup {
+    (hostname: string, options: {
+        all: true;
+        verbatim: true;
+    }): Promise<Array<{
+        address: string;
+        family: 4 | 6;
+    }>>;
+}
+export interface ResolveRemoteTargetOptions {
+    allowLocalNetwork?: boolean;
+    lookup?: RemoteLookup;
+}
+export declare class RemoteNetworkPolicyError extends Error {
+    readonly code: "REMOTE_TARGET_EMPTY" | "REMOTE_TARGET_FORBIDDEN" | "REMOTE_TARGET_INVALID_ADDRESS" | "REMOTE_TARGET_LOOKUP_FAILED" | "REMOTE_TARGET_URL_INVALID";
+    constructor(code: "REMOTE_TARGET_EMPTY" | "REMOTE_TARGET_FORBIDDEN" | "REMOTE_TARGET_INVALID_ADDRESS" | "REMOTE_TARGET_LOOKUP_FAILED" | "REMOTE_TARGET_URL_INVALID", message: string);
+}
+export declare function resolveRemoteTarget(url: URL, options?: ResolveRemoteTargetOptions): Promise<ResolvedRemoteTarget>;

package/dist/core/remote-network-policy.js

@@ -0,0 +1,125 @@
+import { lookup as dnsLookup } from "node:dns/promises";
+import { BlockList, isIP, SocketAddress } from "node:net";
+export class RemoteNetworkPolicyError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "RemoteNetworkPolicyError";
+    }
+}
+const blockedAddresses = new BlockList();
+const loopbackAddresses = new BlockList();
+const mappedIpv4Addresses = new BlockList();
+const ipv4CompatibleAddresses = new BlockList();
+function addIpv4Subnet(address, prefix) {
+    blockedAddresses.addSubnet(address, prefix, "ipv4");
+    blockedAddresses.addSubnet(`::ffff:${address}`, prefix + 96, "ipv6");
+}
+function addLoopbackSubnet(address, prefix) {
+    loopbackAddresses.addSubnet(address, prefix, "ipv4");
+    loopbackAddresses.addSubnet(`::ffff:${address}`, prefix + 96, "ipv6");
+}
+for (const [address, prefix] of [
+    ["0.0.0.0", 8],
+    ["10.0.0.0", 8],
+    ["100.64.0.0", 10],
+    ["169.254.0.0", 16],
+    ["172.16.0.0", 12],
+    ["192.0.0.0", 24],
+    ["192.0.2.0", 24],
+    ["192.88.99.0", 24],
+    ["192.168.0.0", 16],
+    ["198.18.0.0", 15],
+    ["198.51.100.0", 24],
+    ["203.0.113.0", 24],
+    ["224.0.0.0", 4],
+    ["240.0.0.0", 4]
+]) {
+    addIpv4Subnet(address, prefix);
+}
+addLoopbackSubnet("127.0.0.0", 8);
+blockedAddresses.addAddress("100.100.100.200", "ipv4");
+blockedAddresses.addAddress("100.100.100.100", "ipv4");
+for (const [address, prefix] of [
+    ["::", 128],
+    ["100::", 64],
+    ["2001::", 23],
+    ["2001:db8::", 32],
+    ["2002::", 16],
+    ["3fff::", 20],
+    ["5f00::", 16],
+    ["fc00::", 7],
+    ["fe80::", 10],
+    ["ff00::", 8]
+]) {
+    blockedAddresses.addSubnet(address, prefix, "ipv6");
+}
+loopbackAddresses.addAddress("::1", "ipv6");
+mappedIpv4Addresses.addSubnet("::ffff:0:0", 96, "ipv6");
+ipv4CompatibleAddresses.addSubnet("::", 96, "ipv6");
+for (const [address, prefix] of [
+    ["64:ff9b::", 96],
+    ["64:ff9b:1::", 48],
+    ["100:0:0:1::", 64]
+]) {
+    blockedAddresses.addSubnet(address, prefix, "ipv6");
+}
+function normalizeAddress(address, family) {
+    if ((family !== 4 && family !== 6) || isIP(address) !== family) {
+        throw new RemoteNetworkPolicyError("REMOTE_TARGET_INVALID_ADDRESS", "Remote target DNS resolution returned an invalid address.");
+    }
+    const normalized = new SocketAddress({
+        address,
+        port: 0,
+        family: family === 4 ? "ipv4" : "ipv6"
+    });
+    return { address: normalized.address, family };
+}
+function isListed(address, family, list) {
+    return list.check(address, family === 4 ? "ipv4" : "ipv6");
+}
+export async function resolveRemoteTarget(url, options = {}) {
+    const hostname = url.hostname.startsWith("[") && url.hostname.endsWith("]")
+        ? url.hostname.slice(1, -1)
+        : url.hostname;
+    if ((url.protocol !== "http:" && url.protocol !== "https:") || !hostname || isIP(hostname) !== 0) {
+        throw new RemoteNetworkPolicyError("REMOTE_TARGET_URL_INVALID", "Remote target URL must use HTTP or HTTPS with a hostname, not an IP address literal.");
+    }
+    const lookup = options.lookup ?? (async (hostname, lookupOptions) => {
+        const answers = await dnsLookup(hostname, lookupOptions);
+        return answers.map((answer) => ({
+            address: answer.address,
+            family: answer.family
+        }));
+    });
+    let answers;
+    try {
+        answers = await lookup(hostname, { all: true, verbatim: true });
+    }
+    catch {
+        throw new RemoteNetworkPolicyError("REMOTE_TARGET_LOOKUP_FAILED", "Remote target DNS resolution failed.");
+    }
+    if (answers.length === 0) {
+        throw new RemoteNetworkPolicyError("REMOTE_TARGET_EMPTY", "Remote target DNS resolution returned no addresses.");
+    }
+    const normalizedAnswers = answers.map((answer) => normalizeAddress(answer.address, answer.family));
+    for (const answer of normalizedAnswers) {
+        const isLoopback = isListed(answer.address, answer.family, loopbackAddresses);
+        const isMappedIpv4 = answer.family === 6 && isListed(answer.address, answer.family, mappedIpv4Addresses);
+        const isIpv4Compatible = answer.family === 6 && isListed(answer.address, answer.family, ipv4CompatibleAddresses);
+        const isForbidden = isListed(answer.address, answer.family, blockedAddresses)
+            || isIpv4Compatible
+            || (isMappedIpv4 && !isLoopback);
+        if ((isForbidden && !isLoopback) || (isLoopback && !options.allowLocalNetwork)) {
+            throw new RemoteNetworkPolicyError("REMOTE_TARGET_FORBIDDEN", "Remote target resolved to a forbidden address.");
+        }
+    }
+    const selected = normalizedAnswers[0];
+    return {
+        hostname,
+        address: selected.address,
+        family: selected.family,
+        local: isListed(selected.address, selected.family, loopbackAddresses)
+    };
+}

package/dist/core/remote-oauth-readiness.d.ts

@@ -0,0 +1,12 @@
+import { type BoundedHttpRequestOptions, type BoundedHttpResponse } from "./bounded-http-client.js";
+import type { Finding } from "../domain/types.js";
+export type RemoteOAuthReadinessRequest = (rawUrl: string, options?: BoundedHttpRequestOptions) => Promise<BoundedHttpResponse>;
+export interface RemoteOAuthReadinessOptions {
+    request?: RemoteOAuthReadinessRequest;
+    requestOptions?: Pick<BoundedHttpRequestOptions, "allowLocalNetwork" | "lookup" | "timeoutMs">;
+}
+export interface RemoteOAuthReadinessResult {
+    status: "pass" | "fail";
+    findings: Finding[];
+}
+export declare function checkRemoteOAuthReadiness(resourceUrl: string, wwwAuthenticate: Array<string | string[]>, options?: RemoteOAuthReadinessOptions): Promise<RemoteOAuthReadinessResult>;