codex-plugin-doctor 1.51.0 → 1.53.0

package/dist/core/remote-oauth-readiness.js

@@ -0,0 +1,295 @@
+import { isIP } from "node:net";
+import { requestBoundedHttp } from "./bounded-http-client.js";
+const MAX_DISCOVERY_CANDIDATES = 4;
+const MAX_DISCOVERY_TIMEOUT_MS = 3_000;
+function failure(id) {
+    return {
+        status: "fail",
+        findings: [{
+                id,
+                severity: "fail",
+                message: "The remote MCP server authorization metadata could not be validated.",
+                impact: "Protected MCP endpoints cannot be safely assessed without valid OAuth discovery metadata.",
+                suggestedFix: "Publish valid HTTPS protected-resource and authorization-server metadata without credentials, queries, or fragments."
+            }]
+    };
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function mediaType(headers) {
+    const value = headers["content-type"];
+    const source = Array.isArray(value) ? value[0] : value;
+    return typeof source === "string" ? source.split(";", 1)[0]?.trim().toLowerCase() ?? null : null;
+}
+function parseJsonObject(body) {
+    try {
+        const parsed = JSON.parse(body.toString("utf8"));
+        return isPlainObject(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function safeHttpsUrl(value) {
+    if (typeof value !== "string")
+        return null;
+    try {
+        const url = new URL(value);
+        if (url.protocol !== "https:" ||
+            !url.hostname ||
+            url.username ||
+            url.password ||
+            url.search ||
+            url.hash ||
+            url.hostname.startsWith("[") ||
+            isIP(url.hostname) !== 0) {
+            return null;
+        }
+        return value;
+    }
+    catch {
+        return null;
+    }
+}
+function insertWellKnown(resourceUrl, suffix) {
+    const url = new URL(resourceUrl);
+    const path = url.pathname === "/" ? "" : url.pathname.replace(/\/$/, "");
+    return `${url.origin}/.well-known/${suffix}${path}`;
+}
+function oidcDiscoveryUrl(issuer) {
+    const url = new URL(issuer);
+    return `${url.origin}${url.pathname.replace(/\/$/, "")}/.well-known/openid-configuration`;
+}
+function splitTopLevelCommas(value) {
+    const parts = [];
+    let start = 0;
+    let quoted = false;
+    for (let index = 0; index < value.length; index += 1) {
+        const character = value[index];
+        if (quoted && character === "\\") {
+            index += 1;
+            if (index >= value.length)
+                return null;
+            continue;
+        }
+        if (character === "\"") {
+            quoted = !quoted;
+            continue;
+        }
+        if (!quoted && character === ",") {
+            parts.push(value.slice(start, index));
+            start = index + 1;
+        }
+    }
+    return quoted ? null : [...parts, value.slice(start)];
+}
+function parseAuthParam(value) {
+    const match = /^([!#$%&'*+.^`|~\w-]+)[ \t]*=[ \t]*(.*)$/.exec(value);
+    if (match === null)
+        return null;
+    const name = match[1];
+    const rawValue = match[2].trim();
+    if (rawValue.length === 0)
+        return null;
+    if (!rawValue.startsWith("\"")) {
+        return /[\s"]/u.test(rawValue) ? null : { name, value: rawValue };
+    }
+    if (!rawValue.endsWith("\"") || rawValue.length === 1)
+        return null;
+    let decoded = "";
+    for (let index = 1; index < rawValue.length - 1; index += 1) {
+        const character = rawValue[index];
+        if (character === "\\") {
+            index += 1;
+            if (index >= rawValue.length - 1)
+                return null;
+            decoded += rawValue[index];
+            continue;
+        }
+        if (character === "\"")
+            return null;
+        decoded += character;
+    }
+    return { name, value: decoded };
+}
+function parseChallenge(value) {
+    const match = /^([!#$%&'*+.^`|~\w-]+)(?:[ \t]+(.*))?$/.exec(value);
+    if (match === null)
+        return null;
+    const scheme = match[1];
+    const credentials = match[2];
+    if (credentials === undefined || credentials.trim().length === 0)
+        return { scheme, parameter: null };
+    const parameter = parseAuthParam(credentials);
+    if (parameter !== null)
+        return { scheme, parameter };
+    return /^[A-Za-z0-9\-._~+/]+={0,}$/.test(credentials) ? { scheme, parameter: null } : null;
+}
+function parseBearerResourceMetadata(headers) {
+    const values = [];
+    let specified = false;
+    for (const header of headers.flatMap((value) => Array.isArray(value) ? value : [value])) {
+        const parts = splitTopLevelCommas(header);
+        if (parts === null)
+            return null;
+        let scheme = null;
+        for (const part of parts) {
+            const token = part.trim();
+            if (token.length === 0)
+                return null;
+            const parameter = parseAuthParam(token);
+            if (parameter !== null) {
+                if (scheme === null)
+                    return null;
+                if (scheme.toLowerCase() === "bearer" && parameter.name.toLowerCase() === "resource_metadata") {
+                    specified = true;
+                    values.push(parameter.value);
+                }
+                continue;
+            }
+            const challenge = parseChallenge(token);
+            if (challenge === null)
+                return null;
+            scheme = challenge.scheme;
+            if (scheme.toLowerCase() === "bearer" && challenge.parameter?.name.toLowerCase() === "resource_metadata") {
+                specified = true;
+                values.push(challenge.parameter.value);
+            }
+        }
+    }
+    return { specified, values };
+}
+async function fetchMetadata(url, request, requestOptions, deadline) {
+    const remainingMs = deadline - Date.now();
+    if (remainingMs <= 0)
+        return { kind: "unavailable" };
+    let timeout;
+    try {
+        const response = await Promise.race([
+            request(url, {
+                ...requestOptions,
+                timeoutMs: Math.max(1, Math.floor(remainingMs)),
+                method: "GET",
+                headers: { Accept: "application/json" }
+            }),
+            new Promise((_resolve, reject) => {
+                timeout = setTimeout(() => reject(new Error("OAuth discovery timed out.")), remainingMs);
+            })
+        ]);
+        if (response.statusCode === 404)
+            return { kind: "not-found" };
+        if (response.statusCode !== 200 || mediaType(response.headers) !== "application/json") {
+            return { kind: "unavailable" };
+        }
+        const metadata = parseJsonObject(response.body);
+        return metadata === null ? { kind: "invalid" } : { kind: "ok", metadata };
+    }
+    catch {
+        return { kind: "unavailable" };
+    }
+    finally {
+        if (timeout !== undefined)
+            clearTimeout(timeout);
+    }
+}
+function validProtectedResourceMetadata(metadata, resourceUrl) {
+    if (metadata.resource !== resourceUrl || !Array.isArray(metadata.authorization_servers) || metadata.authorization_servers.length === 0) {
+        return null;
+    }
+    const issuers = metadata.authorization_servers.map(safeHttpsUrl);
+    if (!issuers.every((issuer) => issuer !== null))
+        return null;
+    const uniqueIssuers = [...new Set(issuers)];
+    return uniqueIssuers.length <= MAX_DISCOVERY_CANDIDATES ? uniqueIssuers : null;
+}
+function validAuthorizationServerMetadata(metadata, issuer) {
+    return (metadata.issuer === issuer &&
+        safeHttpsUrl(metadata.authorization_endpoint) !== null &&
+        safeHttpsUrl(metadata.token_endpoint) !== null);
+}
+async function authorizationServerIsReady(issuer, request, requestOptions, deadline) {
+    const rfc8414 = await fetchMetadata(insertWellKnown(issuer, "oauth-authorization-server"), request, requestOptions, deadline);
+    if (rfc8414.kind === "ok")
+        return validAuthorizationServerMetadata(rfc8414.metadata, issuer) ? "pass" : "invalid";
+    if (rfc8414.kind === "unavailable")
+        return "unavailable";
+    const oidcUrls = [...new Set([
+            insertWellKnown(issuer, "openid-configuration"),
+            oidcDiscoveryUrl(issuer)
+        ])];
+    for (const oidcUrl of oidcUrls) {
+        const oidc = await fetchMetadata(oidcUrl, request, requestOptions, deadline);
+        if (oidc.kind === "ok")
+            return validAuthorizationServerMetadata(oidc.metadata, issuer) ? "pass" : "invalid";
+        if (oidc.kind === "unavailable")
+            return "unavailable";
+    }
+    return "invalid";
+}
+export async function checkRemoteOAuthReadiness(resourceUrl, wwwAuthenticate, options = {}) {
+    const request = options.request ?? requestBoundedHttp;
+    const explicit = parseBearerResourceMetadata(wwwAuthenticate);
+    if (explicit === null)
+        return failure("plugin.runtime.remote.authorization.metadata.invalid");
+    const metadataCandidates = explicit.specified
+        ? explicit.values.map(safeHttpsUrl)
+        : [
+            insertWellKnown(resourceUrl, "oauth-protected-resource"),
+            `${new URL(resourceUrl).origin}/.well-known/oauth-protected-resource`
+        ].map(safeHttpsUrl);
+    if (!metadataCandidates.every((url) => url !== null)) {
+        return failure("plugin.runtime.remote.authorization.metadata.invalid");
+    }
+    const metadataUrls = [...new Set(metadataCandidates)];
+    if (metadataUrls.length > MAX_DISCOVERY_CANDIDATES)
+        return failure("plugin.runtime.remote.authorization.metadata.invalid");
+    const suppliedTimeoutMs = options.requestOptions?.timeoutMs;
+    const timeoutMs = typeof suppliedTimeoutMs === "number" && Number.isFinite(suppliedTimeoutMs)
+        ? Math.max(0, Math.min(suppliedTimeoutMs, MAX_DISCOVERY_TIMEOUT_MS))
+        : MAX_DISCOVERY_TIMEOUT_MS;
+    const deadline = Date.now() + timeoutMs;
+    let issuers = null;
+    let protectedMetadataFetchedInvalid = false;
+    let protectedMetadataUnavailable = false;
+    for (const metadataUrl of metadataUrls) {
+        const reply = await fetchMetadata(metadataUrl, request, options.requestOptions, deadline);
+        if (reply.kind === "ok") {
+            const candidateIssuers = validProtectedResourceMetadata(reply.metadata, resourceUrl);
+            if (candidateIssuers !== null) {
+                issuers = candidateIssuers;
+                break;
+            }
+            protectedMetadataFetchedInvalid = true;
+            if (!explicit.specified)
+                return failure("plugin.runtime.remote.authorization.metadata.invalid");
+            continue;
+        }
+        if (reply.kind === "invalid") {
+            protectedMetadataFetchedInvalid = true;
+            if (!explicit.specified)
+                return failure("plugin.runtime.remote.authorization.metadata.invalid");
+            continue;
+        }
+        protectedMetadataUnavailable = true;
+        if (!explicit.specified && reply.kind === "unavailable") {
+            return failure("plugin.runtime.remote.authorization.metadata.unavailable");
+        }
+    }
+    if (issuers === null)
+        return failure(protectedMetadataFetchedInvalid
+            ? "plugin.runtime.remote.authorization.metadata.invalid"
+            : protectedMetadataUnavailable
+                ? "plugin.runtime.remote.authorization.metadata.unavailable"
+                : "plugin.runtime.remote.authorization.metadata.invalid");
+    let unavailable = false;
+    for (const issuer of issuers) {
+        const readiness = await authorizationServerIsReady(issuer, request, options.requestOptions, deadline);
+        if (readiness === "pass")
+            return { status: "pass", findings: [] };
+        unavailable ||= readiness === "unavailable";
+    }
+    return failure(unavailable
+        ? "plugin.runtime.remote.authorization.metadata.unavailable"
+        : "plugin.runtime.remote.authorization.metadata.invalid");
+}

package/dist/core/remote-transport-reliability.d.ts

@@ -0,0 +1,18 @@
+import { type BoundedHttpRequestOptions, type BoundedHttpResponse } from "./bounded-http-client.js";
+import type { Finding, RemoteTransportReliabilityScorecard } from "../domain/types.js";
+export interface RemoteTransportReliabilityResult {
+    findings: Finding[];
+    scorecard: RemoteTransportReliabilityScorecard;
+}
+export type RemoteTransportReliabilityRequest = (options: BoundedHttpRequestOptions) => Promise<BoundedHttpResponse>;
+export interface RemoteTransportReliabilityOptions {
+    rawUrl: string;
+    protocolVersion: string;
+    request: (rawUrl: string, options?: BoundedHttpRequestOptions) => Promise<BoundedHttpResponse>;
+    requestTimeoutMs?: number;
+    requestOptions?: Pick<BoundedHttpRequestOptions, "allowLocalNetwork" | "lookup">;
+    sessionId: string | null;
+    allowSessionLifecycle?: boolean;
+    reinitialize: (request: RemoteTransportReliabilityRequest) => Promise<string | null>;
+}
+export declare function probeRemoteTransportReliability(options: RemoteTransportReliabilityOptions): Promise<RemoteTransportReliabilityResult>;

package/dist/core/remote-transport-reliability.js

@@ -0,0 +1,243 @@
+import { BoundedHttpError } from "./bounded-http-client.js";
+import { observeFirstSseEvent } from "./sse-observation.js";
+const DEFAULT_RELIABILITY_TIMEOUT_MS = 3_000;
+const MAX_RELIABILITY_REQUESTS = 6;
+function createScorecard() {
+    return {
+        getSse: "skipped",
+        sessionPropagation: "skipped",
+        resumability: "skipped",
+        disconnectSafety: "skipped",
+        sessionRestart: "skipped",
+        termination: "skipped",
+        overall: "skipped"
+    };
+}
+function finding(id, severity, message, suggestedFix) {
+    return {
+        id,
+        severity,
+        message,
+        impact: "Remote MCP transport reliability could not be verified within the configured safety bounds.",
+        suggestedFix
+    };
+}
+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 validSessionId(value) {
+    return value !== null && /^[\x21-\x7e]+$/.test(value);
+}
+function wait(delayMs) {
+    return new Promise((resolve) => setTimeout(resolve, delayMs));
+}
+function finalize(scorecard, findings) {
+    const statuses = Object.entries(scorecard)
+        .filter(([name]) => name !== "overall")
+        .map(([, status]) => status);
+    scorecard.overall = statuses.includes("fail")
+        ? "fail"
+        : statuses.includes("warn")
+            ? "warn"
+            : statuses.includes("pass")
+                ? "pass"
+                : "skipped";
+    return { findings, scorecard };
+}
+function isSseTimeout(error) {
+    return error instanceof BoundedHttpError
+        && error.code === "REMOTE_HTTP_TIMEOUT"
+        && error.statusCode === 200
+        && mediaType(responseHeader(error.headers ?? {}, "content-type")) === "text/event-stream";
+}
+function classifySseResponse(response, failurePrefix, findings) {
+    if (response.statusCode !== 200) {
+        findings.push(finding(`plugin.runtime.remote.reliability.${failurePrefix}.status`, "fail", "The remote MCP endpoint returned an unsupported SSE transport status.", "Return HTTP 200 for an accepted SSE transport request."));
+        return null;
+    }
+    if (mediaType(responseHeader(response.headers, "content-type")) !== "text/event-stream") {
+        findings.push(finding(`plugin.runtime.remote.reliability.${failurePrefix}.content_type`, "fail", "The remote MCP endpoint returned a non-SSE media type for an SSE transport request.", "Return text/event-stream for accepted SSE transport requests."));
+        return null;
+    }
+    return observeFirstSseEvent(response.body);
+}
+export async function probeRemoteTransportReliability(options) {
+    const scorecard = createScorecard();
+    const findings = [];
+    const timeoutMs = options.requestTimeoutMs ?? DEFAULT_RELIABILITY_TIMEOUT_MS;
+    const deadline = Date.now() + Math.min(timeoutMs, DEFAULT_RELIABILITY_TIMEOUT_MS);
+    let currentSessionId = options.sessionId;
+    let requestCount = 0;
+    let restarted = false;
+    const requestWithinBudget = async (requestOptions) => {
+        if (requestCount >= MAX_RELIABILITY_REQUESTS) {
+            throw new Error("reliability request ceiling reached");
+        }
+        const remainingMs = deadline - Date.now();
+        if (remainingMs <= 0) {
+            throw new BoundedHttpError("REMOTE_HTTP_TIMEOUT", "Remote reliability deadline elapsed.");
+        }
+        requestCount += 1;
+        return options.request(options.rawUrl, {
+            ...requestOptions,
+            ...options.requestOptions,
+            timeoutMs: Math.max(1, Math.min(remainingMs, DEFAULT_RELIABILITY_TIMEOUT_MS))
+        });
+    };
+    const send = async (method, extraHeaders = {}, stopAfter) => {
+        let sessionRestarted = false;
+        for (let attempt = 0; attempt < 2; attempt += 1) {
+            const sessionId = currentSessionId;
+            const headers = {
+                Accept: "text/event-stream",
+                "MCP-Protocol-Version": options.protocolVersion,
+                ...(sessionId === null ? {} : { "MCP-Session-Id": sessionId }),
+                ...(sessionRestarted ? {} : extraHeaders)
+            };
+            if (sessionId !== null) {
+                scorecard.sessionPropagation = "pass";
+            }
+            let response;
+            try {
+                response = await requestWithinBudget({
+                    method,
+                    headers,
+                    stopAfter
+                });
+            }
+            catch (error) {
+                return { error };
+            }
+            if (method === "GET" && sessionId !== null && response.statusCode === 404) {
+                if (restarted) {
+                    scorecard.sessionRestart = "fail";
+                    return { restartFailed: true };
+                }
+                restarted = true;
+                sessionRestarted = true;
+                currentSessionId = null;
+                try {
+                    const replacementSessionId = await options.reinitialize(requestWithinBudget);
+                    if (replacementSessionId !== null && !validSessionId(replacementSessionId)) {
+                        throw new Error("invalid replacement session");
+                    }
+                    currentSessionId = replacementSessionId;
+                    scorecard.sessionRestart = "pass";
+                }
+                catch {
+                    scorecard.sessionRestart = "fail";
+                    return { restartFailed: true };
+                }
+                continue;
+            }
+            return { response, sessionRestarted };
+        }
+        return { restartFailed: true };
+    };
+    const first = await send("GET", {}, (body) => observeFirstSseEvent(body).complete);
+    if (first.restartFailed) {
+        findings.push(finding("plugin.runtime.remote.reliability.session_restart.failed", "fail", "The remote MCP session expired and could not be restarted within the bounded probe.", "Accept a fresh initialize sequence after an expired MCP session."));
+        return finalize(scorecard, findings);
+    }
+    if (first.error) {
+        if (isSseTimeout(first.error)) {
+            scorecard.getSse = "warn";
+            scorecard.disconnectSafety = "warn";
+            findings.push(finding("plugin.runtime.remote.reliability.get.inconclusive", "warn", "The remote MCP SSE stream did not produce a complete event before the bounded observation deadline.", "Emit complete SSE event frames promptly when server-to-client streaming is supported."));
+            return finalize(scorecard, findings);
+        }
+        scorecard.getSse = "fail";
+        findings.push(finding("plugin.runtime.remote.reliability.get.failed", "fail", "The remote MCP SSE transport request could not be completed.", "Keep the Streamable HTTP transport reachable within the configured request bounds."));
+        return finalize(scorecard, findings);
+    }
+    const firstResponse = first.response;
+    if (!firstResponse) {
+        scorecard.getSse = "fail";
+        return finalize(scorecard, findings);
+    }
+    if (firstResponse.statusCode === 405) {
+        scorecard.getSse = "pass";
+    }
+    else {
+        const observation = classifySseResponse(firstResponse, "get", findings);
+        if (observation === null) {
+            scorecard.getSse = "fail";
+            return finalize(scorecard, findings);
+        }
+        if (!observation.complete) {
+            scorecard.getSse = "warn";
+            scorecard.disconnectSafety = "warn";
+            findings.push(finding("plugin.runtime.remote.reliability.get.inconclusive", "warn", "The remote MCP SSE response ended before a complete event could be observed.", "Emit complete SSE event frames when server-to-client streaming is supported."));
+            return finalize(scorecard, findings);
+        }
+        if (observation.malformed) {
+            scorecard.getSse = "fail";
+            scorecard.disconnectSafety = "fail";
+            findings.push(finding("plugin.runtime.remote.reliability.get.malformed", "fail", "The remote MCP endpoint emitted malformed SSE event framing.", "Return complete SSE events with valid id and retry fields."));
+            return finalize(scorecard, findings);
+        }
+        scorecard.getSse = "pass";
+        scorecard.disconnectSafety = "pass";
+        if (observation.eventId !== null) {
+            const remainingMs = deadline - Date.now();
+            if (observation.retryMs !== null) {
+                if (observation.retryMs >= remainingMs) {
+                    scorecard.resumability = "warn";
+                    findings.push(finding("plugin.runtime.remote.reliability.resume.inconclusive", "warn", "The remote MCP SSE retry delay exceeded the remaining bounded observation deadline.", "Advertise an SSE retry delay that fits within the configured probe deadline."));
+                    return finalize(scorecard, findings);
+                }
+                await wait(observation.retryMs);
+            }
+            const resumed = await send("GET", { "Last-Event-ID": observation.eventId }, (body) => observeFirstSseEvent(body).complete);
+            if (resumed.restartFailed) {
+                findings.push(finding("plugin.runtime.remote.reliability.session_restart.failed", "fail", "The remote MCP session expired during SSE resumability validation and could not be restarted.", "Accept one fresh initialize sequence after an expired MCP session."));
+                return finalize(scorecard, findings);
+            }
+            if (resumed.error) {
+                scorecard.resumability = isSseTimeout(resumed.error) ? "warn" : "fail";
+                findings.push(finding(isSseTimeout(resumed.error)
+                    ? "plugin.runtime.remote.reliability.resume.inconclusive"
+                    : "plugin.runtime.remote.reliability.resume.failed", isSseTimeout(resumed.error) ? "warn" : "fail", "The remote MCP SSE resume request could not be completed within the bounded probe.", "Accept one bounded SSE reconnect using Last-Event-ID."));
+                return finalize(scorecard, findings);
+            }
+            if (!resumed.response) {
+                scorecard.resumability = "fail";
+                return finalize(scorecard, findings);
+            }
+            if (resumed.sessionRestarted) {
+                scorecard.resumability = "skipped";
+            }
+            else {
+                const resumeObservation = classifySseResponse(resumed.response, "resume", findings);
+                if (resumeObservation === null || resumeObservation.malformed) {
+                    scorecard.resumability = "fail";
+                    if (resumeObservation?.malformed) {
+                        findings.push(finding("plugin.runtime.remote.reliability.resume.malformed", "fail", "The remote MCP endpoint emitted malformed SSE framing after a resume request.", "Return complete SSE events with valid id and retry fields after reconnecting."));
+                    }
+                    return finalize(scorecard, findings);
+                }
+                scorecard.resumability = resumeObservation.complete ? "pass" : "warn";
+                if (!resumeObservation.complete) {
+                    findings.push(finding("plugin.runtime.remote.reliability.resume.inconclusive", "warn", "The remote MCP SSE resume response ended before a complete event could be observed.", "Emit complete SSE events after accepting a reconnect."));
+                    return finalize(scorecard, findings);
+                }
+            }
+        }
+    }
+    if (!options.allowSessionLifecycle || currentSessionId === null) {
+        return finalize(scorecard, findings);
+    }
+    const terminated = await send("DELETE");
+    if (terminated.restartFailed || terminated.error || !terminated.response
+        || (terminated.response.statusCode !== 405 && (terminated.response.statusCode < 200 || terminated.response.statusCode >= 300))) {
+        scorecard.termination = "fail";
+        findings.push(finding("plugin.runtime.remote.reliability.termination.failed", "fail", "The remote MCP session could not be terminated with the approved lifecycle request.", "Return a successful response or HTTP 405 for a bounded MCP session DELETE request."));
+        return finalize(scorecard, findings);
+    }
+    scorecard.termination = "pass";
+    return finalize(scorecard, findings);
+}

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

@@ -0,0 +1,7 @@
+export interface RemoteUrlInspection {
+    parsedUrl: URL | null;
+    sanitizedUrl: string | null;
+    isLoopbackHost: boolean;
+    issues: Array<"invalid" | "unsupported_scheme" | "credentials" | "query" | "fragment" | "ip_literal" | "insecure_non_loopback">;
+}
+export declare function inspectRemoteMcpUrl(rawUrl: string): RemoteUrlInspection;

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

@@ -0,0 +1,49 @@
+function isIpLiteral(hostname) {
+    return (/^\d{1,3}(?:\.\d{1,3}){3}$/.test(hostname) ||
+        /^\[[0-9a-f:.]+\]$/i.test(hostname));
+}
+export function inspectRemoteMcpUrl(rawUrl) {
+    let parsedUrl;
+    try {
+        parsedUrl = new URL(rawUrl);
+    }
+    catch {
+        return {
+            parsedUrl: null,
+            sanitizedUrl: null,
+            isLoopbackHost: false,
+            issues: ["invalid"]
+        };
+    }
+    const issues = [];
+    const isSupportedScheme = parsedUrl.protocol === "http:" || parsedUrl.protocol === "https:";
+    const isAbsoluteHttpUrl = /^https?:\/\//i.test(rawUrl);
+    const isLoopbackHost = parsedUrl.hostname.toLowerCase() === "localhost";
+    if (!isSupportedScheme) {
+        issues.push("unsupported_scheme");
+    }
+    else if (!isAbsoluteHttpUrl || !parsedUrl.hostname) {
+        issues.push("invalid");
+    }
+    if (parsedUrl.username || parsedUrl.password) {
+        issues.push("credentials");
+    }
+    if (parsedUrl.search || rawUrl.includes("?")) {
+        issues.push("query");
+    }
+    if (parsedUrl.hash || rawUrl.includes("#")) {
+        issues.push("fragment");
+    }
+    if (isIpLiteral(parsedUrl.hostname)) {
+        issues.push("ip_literal");
+    }
+    if (parsedUrl.protocol === "http:" && !isLoopbackHost) {
+        issues.push("insecure_non_loopback");
+    }
+    return {
+        parsedUrl,
+        sanitizedUrl: `${parsedUrl.origin}${parsedUrl.pathname}`,
+        isLoopbackHost,
+        issues
+    };
+}

package/dist/core/runtime-plan.d.ts

@@ -4,6 +4,7 @@ import type { RuntimeExecutionEvidence, RuntimeSandboxMode } from "../domain/typ
 type RuntimePlanStatus = "pass" | "warn" | "fail";
 type RuntimePlanRiskLevel = "low" | "medium" | "high";
 type RuntimePlanTransport = "stdio" | "http";
+type RemoteNetworkClass = "public_https" | "loopback_http" | "loopback_https" | "invalid";
 export interface RuntimePlanServer {
     name: string;
     transport: RuntimePlanTransport;
@@ -11,7 +12,9 @@ export interface RuntimePlanServer {
     args: string[];
     cwd: string | null;
     url: string | null;
+    networkClass?: RemoteNetworkClass;
     probeMethods: string[];
+    approvalRequirements?: string[];
     riskLevel: RuntimePlanRiskLevel;
     riskReasons: string[];
 }