codex-plugin-doctor 1.51.0 → 1.52.0

package/README.md

@@ -78,10 +78,21 @@ Runtime MCP validation with `--runtime`:
 - paginated list responses
 - runtime capability scorecard
 - redacted verbose transcript with `--verbose-runtime`
-- optional runtime approval gating with a precomputed `doctor runtime-plan` digest
-- optional Docker isolation for local Node.js stdio servers with `--sandbox docker`
-
-Output formats:
+- optional runtime approval gating with a precomputed `doctor runtime-plan` digest
+- optional Docker isolation for local Node.js stdio servers with `--sandbox docker`
+
+### Remote MCP Readiness
+
+Remote MCP runtime probing is disabled until you explicitly pass `--allow-network`. Local endpoints also require `--allow-local-network`:
+
+```bash
+codex-plugin-doctor check ./remote-mcp --runtime --allow-network
+codex-plugin-doctor check ./remote-mcp --runtime --allow-network --allow-local-network
+```
+
+The probe makes only bounded, read-only protocol and OAuth metadata-discovery requests, redacts report output, and applies SSRF controls. It does not authenticate or follow redirects. See [Remote MCP Readiness](./docs/architecture/remote-mcp-readiness.md).
+
+Output formats:
 
 - human text output
 - JSON reports
@@ -427,9 +438,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - uses: Esquetta/CodexPluginDoctor@v1.51.0
+      - uses: Esquetta/CodexPluginDoctor@v1.52.0
         with:
-          version: "1.51.0"
+          version: "1.52.0"
           path: .
           runtime: "true"
           policy: codex-publish

package/dist/core/bounded-http-client.d.ts

@@ -0,0 +1,23 @@
+import { type RemoteLookup } from "./remote-network-policy.js";
+export interface BoundedHttpRequestOptions {
+    allowLocalNetwork?: boolean;
+    lookup?: RemoteLookup;
+    timeoutMs?: number;
+    maxResponseBytes?: number;
+    method?: string;
+    body?: string | Buffer;
+    headers?: Record<string, string | undefined>;
+    stopAfter?: (body: Buffer) => boolean;
+}
+export interface BoundedHttpResponse {
+    statusCode: number;
+    headers: Record<string, string | string[]>;
+    body: Buffer;
+}
+export declare class BoundedHttpError extends Error {
+    readonly code: "REMOTE_HTTP_ENCODING_UNSUPPORTED" | "REMOTE_HTTP_HEADER_FORBIDDEN" | "REMOTE_HTTP_OPTIONS_INVALID" | "REMOTE_HTTP_PEER_MISMATCH" | "REMOTE_HTTP_REDIRECT" | "REMOTE_HTTP_REQUEST_FAILED" | "REMOTE_HTTP_RESPONSE_TOO_LARGE" | "REMOTE_HTTP_STOP_CONDITION_FAILED" | "REMOTE_HTTP_TIMEOUT" | "REMOTE_HTTP_URL_CREDENTIALS" | "REMOTE_HTTP_URL_UNSUPPORTED";
+    readonly statusCode?: number | undefined;
+    readonly headers?: Record<string, string | string[]> | undefined;
+    constructor(code: "REMOTE_HTTP_ENCODING_UNSUPPORTED" | "REMOTE_HTTP_HEADER_FORBIDDEN" | "REMOTE_HTTP_OPTIONS_INVALID" | "REMOTE_HTTP_PEER_MISMATCH" | "REMOTE_HTTP_REDIRECT" | "REMOTE_HTTP_REQUEST_FAILED" | "REMOTE_HTTP_RESPONSE_TOO_LARGE" | "REMOTE_HTTP_STOP_CONDITION_FAILED" | "REMOTE_HTTP_TIMEOUT" | "REMOTE_HTTP_URL_CREDENTIALS" | "REMOTE_HTTP_URL_UNSUPPORTED", message: string, statusCode?: number | undefined, headers?: Record<string, string | string[]> | undefined);
+}
+export declare function requestBoundedHttp(rawUrl: string, options?: BoundedHttpRequestOptions): Promise<BoundedHttpResponse>;

package/dist/core/bounded-http-client.js

@@ -0,0 +1,240 @@
+import * as http from "node:http";
+import * as https from "node:https";
+import { BlockList, isIP } from "node:net";
+import { resolveRemoteTarget } from "./remote-network-policy.js";
+const DEFAULT_TIMEOUT_MS = 3_000;
+const DEFAULT_MAX_RESPONSE_BYTES = 1_024 * 1_024;
+const allowedRequestHeaders = new Set([
+    "accept",
+    "content-type",
+    "mcp-protocol-version",
+    "mcp-session-id",
+    "user-agent"
+]);
+const safeResponseHeaders = new Set([
+    "content-type",
+    "www-authenticate",
+    "mcp-session-id",
+    "mcp-protocol-version",
+    "location"
+]);
+export class BoundedHttpError extends Error {
+    code;
+    statusCode;
+    headers;
+    constructor(code, message, statusCode, headers) {
+        super(message);
+        this.code = code;
+        this.statusCode = statusCode;
+        this.headers = headers;
+        this.name = "BoundedHttpError";
+    }
+}
+function validateHeaders(headers) {
+    const validated = {};
+    for (const [name, value] of Object.entries(headers ?? {})) {
+        if (value === undefined) {
+            continue;
+        }
+        const normalizedName = name.toLowerCase();
+        if (!allowedRequestHeaders.has(normalizedName)) {
+            throw new BoundedHttpError("REMOTE_HTTP_HEADER_FORBIDDEN", `Remote HTTP request header is not allowed: ${normalizedName}.`);
+        }
+        if (normalizedName in validated || typeof value !== "string") {
+            throw new BoundedHttpError("REMOTE_HTTP_HEADER_FORBIDDEN", `Remote HTTP request header must be a single valid string: ${normalizedName}.`);
+        }
+        try {
+            http.validateHeaderValue(normalizedName, value);
+        }
+        catch {
+            throw new BoundedHttpError("REMOTE_HTTP_HEADER_FORBIDDEN", `Remote HTTP request header must be a single valid string: ${normalizedName}.`);
+        }
+        validated[normalizedName] = value;
+    }
+    return validated;
+}
+function validateOptions(options) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const maxResponseBytes = options.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES;
+    if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > DEFAULT_TIMEOUT_MS
+        || !Number.isInteger(maxResponseBytes) || maxResponseBytes < 1 || maxResponseBytes > DEFAULT_MAX_RESPONSE_BYTES) {
+        throw new BoundedHttpError("REMOTE_HTTP_OPTIONS_INVALID", "Remote HTTP request options are invalid.");
+    }
+    return { timeoutMs, maxResponseBytes };
+}
+async function resolveWithinDeadline(url, options, timeoutMs) {
+    let timer;
+    try {
+        return await Promise.race([
+            resolveRemoteTarget(url, {
+                allowLocalNetwork: options.allowLocalNetwork,
+                lookup: options.lookup
+            }),
+            new Promise((_resolve, reject) => {
+                timer = setTimeout(() => {
+                    reject(new BoundedHttpError("REMOTE_HTTP_TIMEOUT", "Remote HTTP request timed out."));
+                }, timeoutMs);
+            })
+        ]);
+    }
+    finally {
+        if (timer !== undefined) {
+            clearTimeout(timer);
+        }
+    }
+}
+function selectSafeHeaders(headers) {
+    const selected = {};
+    for (const name of safeResponseHeaders) {
+        const value = headers[name];
+        if (value !== undefined) {
+            selected[name] = value;
+        }
+    }
+    return selected;
+}
+function hasIdentityContentEncoding(headers) {
+    const value = headers["content-encoding"];
+    const values = Array.isArray(value) ? value : value === undefined ? [] : [value];
+    return values.every((entry) => entry.toLowerCase() === "identity");
+}
+function matchesTargetPeer(target, remoteAddress) {
+    if (remoteAddress === undefined || isIP(remoteAddress) === 0) {
+        return false;
+    }
+    const peers = new BlockList();
+    peers.addAddress(target.address, target.family === 4 ? "ipv4" : "ipv6");
+    if (target.family === 4) {
+        peers.addAddress(`::ffff:${target.address}`, "ipv6");
+    }
+    return peers.check(remoteAddress, isIP(remoteAddress) === 4 ? "ipv4" : "ipv6");
+}
+export async function requestBoundedHttp(rawUrl, options = {}) {
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        throw new BoundedHttpError("REMOTE_HTTP_URL_UNSUPPORTED", "Remote HTTP URL must be absolute HTTP or HTTPS.");
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new BoundedHttpError("REMOTE_HTTP_URL_UNSUPPORTED", "Remote HTTP URL must be absolute HTTP or HTTPS.");
+    }
+    if (url.username || url.password) {
+        throw new BoundedHttpError("REMOTE_HTTP_URL_CREDENTIALS", "Remote HTTP URL must not include credentials.");
+    }
+    const { timeoutMs, maxResponseBytes } = validateOptions(options);
+    const headers = validateHeaders(options.headers);
+    const deadline = Date.now() + timeoutMs;
+    const target = await resolveWithinDeadline(url, options, timeoutMs);
+    const remainingMs = deadline - Date.now();
+    if (remainingMs <= 0) {
+        throw new BoundedHttpError("REMOTE_HTTP_TIMEOUT", "Remote HTTP request timed out.");
+    }
+    const transport = url.protocol === "https:" ? https : http;
+    return new Promise((resolve, reject) => {
+        let request;
+        let response;
+        let settled = false;
+        const timeout = setTimeout(() => {
+            fail(new BoundedHttpError("REMOTE_HTTP_TIMEOUT", "Remote HTTP request timed out."));
+        }, remainingMs);
+        const fail = (error) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timeout);
+            response?.destroy();
+            request?.destroy();
+            reject(error);
+        };
+        const complete = (body) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timeout);
+            response?.destroy();
+            request?.destroy();
+            resolve({
+                statusCode: response?.statusCode ?? 0,
+                headers: response ? selectSafeHeaders(response.headers) : {},
+                body
+            });
+        };
+        try {
+            request = transport.request({
+                protocol: url.protocol,
+                hostname: url.hostname,
+                port: url.port || undefined,
+                path: `${url.pathname}${url.search}`,
+                method: options.method ?? "GET",
+                headers,
+                agent: false,
+                lookup: (_hostname, lookupOptions, callback) => {
+                    if (lookupOptions.all) {
+                        callback(null, [{ address: target.address, family: target.family }]);
+                        return;
+                    }
+                    callback(null, target.address, target.family);
+                }
+            });
+        }
+        catch {
+            fail(new BoundedHttpError("REMOTE_HTTP_REQUEST_FAILED", "Remote HTTP request failed."));
+            return;
+        }
+        request.once("error", () => {
+            fail(new BoundedHttpError("REMOTE_HTTP_REQUEST_FAILED", "Remote HTTP request failed."));
+        });
+        request.once("response", (incoming) => {
+            response = incoming;
+            const safeHeaders = selectSafeHeaders(incoming.headers);
+            if (!matchesTargetPeer(target, incoming.socket.remoteAddress)) {
+                fail(new BoundedHttpError("REMOTE_HTTP_PEER_MISMATCH", "Remote HTTP peer did not match the resolved target."));
+                return;
+            }
+            if ((incoming.statusCode ?? 0) >= 300 && (incoming.statusCode ?? 0) < 400) {
+                fail(new BoundedHttpError("REMOTE_HTTP_REDIRECT", "Remote HTTP redirects are not allowed.", incoming.statusCode, safeHeaders));
+                return;
+            }
+            if (!hasIdentityContentEncoding(incoming.headers)) {
+                fail(new BoundedHttpError("REMOTE_HTTP_ENCODING_UNSUPPORTED", "Remote HTTP response content encoding must be identity."));
+                return;
+            }
+            const chunks = [];
+            let receivedBytes = 0;
+            incoming.on("data", (chunk) => {
+                receivedBytes += chunk.length;
+                if (receivedBytes > maxResponseBytes) {
+                    fail(new BoundedHttpError("REMOTE_HTTP_RESPONSE_TOO_LARGE", "Remote HTTP response exceeded the configured size limit."));
+                    return;
+                }
+                chunks.push(chunk);
+                const body = Buffer.concat(chunks);
+                let shouldStop;
+                try {
+                    shouldStop = options.stopAfter?.(body) ?? false;
+                }
+                catch {
+                    fail(new BoundedHttpError("REMOTE_HTTP_STOP_CONDITION_FAILED", "Remote HTTP stop condition failed."));
+                    return;
+                }
+                if (shouldStop) {
+                    complete(body);
+                    return;
+                }
+            });
+            incoming.once("error", () => {
+                fail(new BoundedHttpError("REMOTE_HTTP_REQUEST_FAILED", "Remote HTTP request failed."));
+            });
+            incoming.once("end", () => {
+                if (!settled) {
+                    complete(Buffer.concat(chunks));
+                }
+            });
+        });
+        request.end(options.body);
+    });
+}

package/dist/core/output-contract.js

@@ -35,6 +35,27 @@ const runtimeConformanceSchema = {
     ],
     additionalProperties: false
 };
+const remoteRuntimeScorecardSchema = {
+    type: "object",
+    properties: {
+        transport: runtimeCapabilityStatusSchema,
+        networkSafety: runtimeCapabilityStatusSchema,
+        initialize: runtimeCapabilityStatusSchema,
+        contentType: runtimeCapabilityStatusSchema,
+        session: {
+            type: "string",
+            enum: ["absent", "present-valid", "present-invalid"]
+        },
+        protocolHeaders: runtimeCapabilityStatusSchema,
+        authorization: runtimeCapabilityStatusSchema,
+        overall: {
+            type: "string",
+            enum: ["pass", "warn", "fail", "skipped"]
+        }
+    },
+    required: ["transport", "networkSafety", "initialize", "contentType", "session", "protocolHeaders", "authorization", "overall"],
+    additionalProperties: false
+};
 const runtimeScorecardSchema = {
     type: "object",
     properties: {
@@ -46,7 +67,8 @@ const runtimeScorecardSchema = {
         resourceTemplatesList: runtimeCapabilityStatusSchema,
         promptsList: runtimeCapabilityStatusSchema,
         promptGet: runtimeCapabilityStatusSchema,
-        conformance: runtimeConformanceSchema
+        conformance: runtimeConformanceSchema,
+        remote: remoteRuntimeScorecardSchema
     },
     required: [
         "initialize",

package/dist/core/release-check.d.ts

@@ -41,6 +41,8 @@ export interface BuildReleaseCheckOptions {
     env?: Record<string, string | undefined>;
     platform?: NodeJS.Platform;
     runtime?: boolean;
+    allowNetwork?: boolean;
+    allowLocalNetwork?: boolean;
     runtimeSandbox?: RuntimeSandboxMode;
     runCheck?: (targetPath: string, options: CheckOptions) => Promise<CheckResult>;
 }

package/dist/core/release-check.js

@@ -106,6 +106,8 @@ export async function buildReleaseCheck(targetPath, options = {}) {
     const runtimeProbeEnabled = options.runtime ?? false;
     const validationResult = await (options.runCheck ?? validatePlugin)(resolvedPath, {
         runtime: runtimeProbeEnabled,
+        ...(options.allowNetwork ? { allowNetwork: true } : {}),
+        ...(options.allowLocalNetwork ? { allowLocalNetwork: true } : {}),
         ...(options.runtimeSandbox ? { runtimeSandbox: options.runtimeSandbox } : {})
     });
     const securityResult = await buildSecurityAudit(resolvedPath);

package/dist/core/release-evidence.d.ts

@@ -111,6 +111,8 @@ export interface BuildDoctorReleaseEvidenceOptions {
     requireRuntimeApproval?: boolean;
     runtimeApprovalDigest?: string | null;
     runtime?: boolean;
+    allowNetwork?: boolean;
+    allowLocalNetwork?: boolean;
     sandbox?: RuntimeSandboxMode;
     environment?: CompatibilityEnvironment;
     runCheck?: (targetPath: string, options?: CheckOptions) => Promise<CheckResult>;

package/dist/core/release-evidence.js

@@ -192,17 +192,126 @@ function signReleaseEvidence(report, signingKey, keyHint) {
         keyHint
     };
 }
+function buildRuntimeApprovalFailureReport(rootPath, runtimePlan, runtimeApproval, options) {
+    const generatedAt = new Date().toISOString();
+    const emptyDigest = sha256("");
+    const failureMessage = "Release evidence checks were not run because runtime approval did not pass.";
+    const report = {
+        schemaVersion: "1.0.0",
+        kind: "doctor.release.evidence",
+        generatedAt,
+        version: packageVersion,
+        targetPath: rootPath,
+        status: "fail",
+        exitCode: 1,
+        releaseReady: false,
+        summary: {
+            attestation: "fail",
+            attestationVerification: "fail",
+            corpus: "fail",
+            performance: "fail",
+            releaseGates: "fail",
+            runtimeApproval: "fail",
+            security: "fail",
+            trust: "fail"
+        },
+        releaseGates: {
+            status: "fail",
+            checks: [{ id: "runtime.approval", status: "fail", message: runtimeApproval.message }]
+        },
+        runtimeApproval,
+        ...(options.runtime ? { execution: runtimePlan.execution } : {}),
+        package: { name: null, version: null, private: null },
+        git: { commit: null, tag: null, dirty: null },
+        attestation: {
+            schemaVersion: "1.0.0",
+            kind: "doctor.attestation",
+            generatedAt,
+            version: packageVersion,
+            targetPath: rootPath,
+            subject: { name: "unavailable", version: null, description: null },
+            packageFingerprint: { algorithm: "sha256", digest: emptyDigest, files: { total: 0, bytes: 0 } },
+            reportDigest: { algorithm: "sha256", digest: emptyDigest },
+            summary: {
+                status: "fail",
+                validation: { status: "fail", findingCount: 0 },
+                security: { status: "fail", score: 0, findingCount: 0 },
+                compatibility: { failedClients: [] },
+                trust: { status: "fail", score: 0, findingCount: 0 },
+                recommendations: { actionCount: 0 }
+            },
+            verification: { recomputeCommand: "", notes: [failureMessage] },
+            signature: { status: "unsigned", reason: failureMessage }
+        },
+        attestationVerification: {
+            schemaVersion: "1.0.0",
+            kind: "doctor.attestation.verification",
+            generatedAt,
+            artifactPath: "inline:doctor.release-evidence.attestation",
+            targetPath: rootPath,
+            status: "fail",
+            exitCode: 1,
+            summary: { packageFingerprint: "fail", reportDigest: "fail", signature: "fail" },
+            unsignedFields: [],
+            checks: [{ id: "runtime.approval", status: "fail", message: runtimeApproval.message }]
+        },
+        corpus: {
+            schemaVersion: "1.0.0",
+            kind: "doctor.validation.corpus",
+            generatedAt,
+            version: packageVersion,
+            summary: { status: "fail", caseCount: 0, passedExpectations: 0, failedExpectations: 0, runtimeCases: 0 },
+            cases: []
+        },
+        performance: {
+            schemaVersion: "1.0.0",
+            kind: "doctor.perf",
+            generatedAt,
+            targetPath: rootPath,
+            status: "fail",
+            exitCode: 1,
+            summary: {
+                stageCount: 0,
+                slowestStage: "total",
+                totalDurationMs: 0,
+                validationStatus: "fail",
+                securityStatus: "fail",
+                trustScore: 0,
+                compatibilityFailures: 0,
+                thresholdFailures: 0
+            },
+            stages: [],
+            thresholds: []
+        },
+        security: { status: "fail", score: 0, findingCounts: { fail: 0, warn: 0, total: 0 } },
+        trust: { status: "fail", score: 0, findingCounts: { fail: 0, warn: 0, total: 0 } }
+    };
+    return {
+        ...report,
+        evidenceSignature: signReleaseEvidence(report, options.signingKey, `env:${options.signingKeyEnv}`)
+    };
+}
 export async function buildDoctorReleaseEvidenceReport(targetPath, options) {
     const rootPath = path.resolve(targetPath);
+    const runtimePlan = await buildDoctorRuntimePlan(rootPath, new Date().toISOString(), options.sandbox ? { sandbox: options.sandbox } : {});
+    const runtimeApproval = evaluateRuntimeApproval(runtimePlan, {
+        required: options.requireRuntimeApproval ?? false,
+        approvedDigest: options.runtimeApprovalDigest
+    });
+    if (!runtimeApprovalPassed(runtimeApproval)) {
+        return buildRuntimeApprovalFailureReport(rootPath, runtimePlan, runtimeApproval, options);
+    }
     const security = await buildSecurityAudit(rootPath);
     const runCheck = options.runCheck ?? validatePlugin;
     const checkOptions = options.runtime
         ? {
             runtime: true,
+            ...(options.allowNetwork ? { allowNetwork: true } : {}),
+            ...(options.allowLocalNetwork ? { allowLocalNetwork: true } : {}),
             ...(options.sandbox ? { runtimeSandbox: options.sandbox } : {})
         }
         : {};
-    const [attestation, corpus, performance, trust, packageMetadata, git, runtimePlan] = await Promise.all([
+    const [attestation, corpus, performance, trust, packageMetadata, git] = await Promise.all([
         buildDoctorAttestation(rootPath, {
             signingKey: options.signingKey,
             signingKeyHint: `env:${options.signingKeyEnv}`,
@@ -216,8 +325,7 @@ export async function buildDoctorReleaseEvidenceReport(targetPath, options) {
         }),
         buildTrustScore(rootPath, { securityAudit: security }),
         readPackageMetadata(rootPath),
-        readGitMetadata(rootPath),
-        buildDoctorRuntimePlan(rootPath, new Date().toISOString(), options.sandbox ? { sandbox: options.sandbox } : {})
+        readGitMetadata(rootPath)
     ]);
     const normalizedPackageMetadata = {
         name: packageMetadata.name ?? attestation.subject.name,
@@ -229,10 +337,6 @@ export async function buildDoctorReleaseEvidenceReport(targetPath, options) {
         artifactPath: "inline:doctor.release-evidence.attestation"
     });
     const releaseGates = buildReleaseGateReport(git, options);
-    const runtimeApproval = evaluateRuntimeApproval(runtimePlan, {
-        required: options.requireRuntimeApproval ?? false,
-        approvedDigest: options.runtimeApprovalDigest
-    });
     const partialReport = {
         schemaVersion: "1.0.0",
         kind: "doctor.release.evidence",

package/dist/core/remote-mcp-probe.d.ts

@@ -0,0 +1,16 @@
+import { type BoundedHttpRequestOptions, type BoundedHttpResponse } from "./bounded-http-client.js";
+import { type RemoteLookup } from "./remote-network-policy.js";
+import type { Finding, RemoteRuntimeScorecard } from "../domain/types.js";
+export type RemoteMcpRequest = (rawUrl: string, options?: BoundedHttpRequestOptions) => Promise<BoundedHttpResponse>;
+export interface RemoteMcpProbeOptions {
+    allowNetwork?: boolean;
+    allowLocalNetwork?: boolean;
+    requestTimeoutMs?: number;
+    lookup?: RemoteLookup;
+    request?: RemoteMcpRequest;
+}
+export interface RemoteMcpProbeResult {
+    findings: Finding[];
+    scorecard: RemoteRuntimeScorecard;
+}
+export declare function probeRemoteMcpServer(serverName: string, rawUrl: string, options?: RemoteMcpProbeOptions): Promise<RemoteMcpProbeResult>;