@silver886/mcp-proxy 0.1.4 → 0.2.0

package/dist/proxy/pairing/config.js

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validatePairingConfig = validatePairingConfig;
+const protocol_js_1 = require("../../shared/protocol.js");
+const constants_js_1 = require("../core/constants.js");
+const validation_js_1 = require("./validation.js");
+// Validate a PairingConfig submitted by the setup page. Pure: returns the
+// canonicalised host list (tunnelUrl reduced to its origin so query strings
+// /paths can't smuggle through) or an error string. Centralised here rather
+// than inlined in handleComplete so the rules are reviewable independently
+// of the orchestrator. Every failure mode produces a human-readable error
+// the setup page surfaces back to the user.
+function validatePairingConfig(cfg) {
+    if (!cfg || cfg.sealed !== true)
+        return { ok: false, error: "config must be sealed" };
+    if (!Array.isArray(cfg.hosts) || cfg.hosts.length === 0) {
+        return { ok: false, error: "hosts must be a non-empty array" };
+    }
+    if (cfg.selectedServers !== undefined) {
+        if (!Array.isArray(cfg.selectedServers)) {
+            return { ok: false, error: "selectedServers must be an array if provided" };
+        }
+        // `undefined` means "allow all", which is a valid distinct shape. An
+        // explicit empty array would seal a config that exposes zero servers —
+        // exactly what the UI's "must select at least one" rule prevents on the
+        // client. Reject it here so a direct caller of /pair/complete can't
+        // bypass that gate and persist a paired-but-empty proxy.
+        if (cfg.selectedServers.length === 0) {
+            return { ok: false, error: "selectedServers must not be empty if provided" };
+        }
+    }
+    if (cfg.selectedTools !== undefined && !Array.isArray(cfg.selectedTools)) {
+        return { ok: false, error: "selectedTools must be an array if provided" };
+    }
+    const seen = new Set();
+    const validatedHosts = [];
+    for (const h of cfg.hosts) {
+        if (!h || typeof h !== "object")
+            return { ok: false, error: "each host must be an object" };
+        if (typeof h.id !== "string" || !h.id)
+            return { ok: false, error: "host.id is required" };
+        const reason = (0, protocol_js_1.validateServerName)(h.id);
+        if (reason)
+            return { ok: false, error: `host.id "${h.id}" ${reason}` };
+        if (seen.has(h.id))
+            return { ok: false, error: `duplicate host.id "${h.id}"` };
+        seen.add(h.id);
+        if (typeof h.tunnelUrl !== "string" || !h.tunnelUrl) {
+            return { ok: false, error: `host "${h.id}".tunnelUrl is required` };
+        }
+        if (typeof h.authToken !== "string" || !h.authToken) {
+            return { ok: false, error: `host "${h.id}".authToken is required` };
+        }
+        const validatedUrl = (0, validation_js_1.allowedTunnelUrl)(h.tunnelUrl);
+        if (!validatedUrl) {
+            return { ok: false, error: `host "${h.id}".tunnelUrl is not on the allowlist (must be https on a Cloudflare tunnel domain)` };
+        }
+        validatedHosts.push({
+            id: h.id,
+            tunnelUrl: validatedUrl.origin,
+            authToken: h.authToken,
+            ...(typeof h.label === "string" && h.label ? { label: h.label } : {}),
+        });
+    }
+    // selectedServers entries must reference hosts we actually know about,
+    // otherwise an attacker (or a stale UI) could shape the config so the
+    // server-level allow list never triggered. Catching it here keeps the
+    // invariant on the way IN to ProxyServer state.
+    //
+    // Server names may themselves contain `__`, so we don't `split` — we
+    // take the prefix before the FIRST `__` as the hostId and require the
+    // remainder (the serverName) to be non-empty so a malformed entry like
+    // `host__` doesn't sneak through as a valid-looking allowlist line that
+    // can never match any real server.
+    const validHostIds = new Set(validatedHosts.map((h) => h.id));
+    if (cfg.selectedServers) {
+        for (const entry of cfg.selectedServers) {
+            if (typeof entry !== "string") {
+                return { ok: false, error: `selectedServers entries must look like "<hostId>__<serverName>"` };
+            }
+            const sep = entry.indexOf(constants_js_1.TOOL_SEPARATOR);
+            if (sep <= 0 || sep + constants_js_1.TOOL_SEPARATOR.length >= entry.length) {
+                return { ok: false, error: `selectedServers entry "${entry}" must look like "<hostId>__<serverName>"` };
+            }
+            const hostId = entry.slice(0, sep);
+            if (!validHostIds.has(hostId)) {
+                return { ok: false, error: `selectedServers references unknown host "${hostId}"` };
+            }
+        }
+    }
+    // selectedTools entries are full prefixed tool names
+    // `<hostId>__<serverName>__<toolName>`. We can't validate <toolName>
+    // here (tools are discovered post-pair), but the prefix MUST point at
+    // an exposed server AND the entry must contain enough segments to
+    // actually carry a tool name: an entry whose server prefix isn't in
+    // selectedServers (when defined) — or whose hostId isn't a known host
+    // (when selectedServers is omitted) — is unreachable noise that hides
+    // bugs in the UI or stale configs. Tool/server names may themselves
+    // contain `__`, so we prefix-match the allowed scope rather than
+    // splitting on the separator. Shape is enforced separately by requiring
+    // at least two `__` occurrences — the prefix-match alone degraded to a
+    // hostId-only check when `selectedServers` was omitted, letting entries
+    // like `host__bogus` survive without a tool segment.
+    if (cfg.selectedTools) {
+        const allowedServerPrefixes = cfg.selectedServers
+            ? cfg.selectedServers.map((s) => `${s}${constants_js_1.TOOL_SEPARATOR}`)
+            : Array.from(validHostIds).map((id) => `${id}${constants_js_1.TOOL_SEPARATOR}`);
+        const scopeLabel = cfg.selectedServers ? "selectedServers" : "any known host";
+        for (const entry of cfg.selectedTools) {
+            if (typeof entry !== "string" || !entry) {
+                return { ok: false, error: "selectedTools entries must be non-empty strings" };
+            }
+            const firstSep = entry.indexOf(constants_js_1.TOOL_SEPARATOR);
+            const secondSep = firstSep < 0 ? -1 : entry.indexOf(constants_js_1.TOOL_SEPARATOR, firstSep + constants_js_1.TOOL_SEPARATOR.length);
+            if (firstSep < 0 || secondSep < 0) {
+                return { ok: false, error: `selectedTools entry "${entry}" must look like "<hostId>__<serverName>__<toolName>"` };
+            }
+            const matchedPrefix = allowedServerPrefixes.find((p) => entry.startsWith(p));
+            if (!matchedPrefix) {
+                return { ok: false, error: `selectedTools entry "${entry}" does not reference a server in ${scopeLabel}` };
+            }
+            // Must have at least one character after the matched server prefix
+            // — i.e. an actual tool segment, not the prefix on its own.
+            if (entry.length <= matchedPrefix.length) {
+                return { ok: false, error: `selectedTools entry "${entry}" is missing the tool name` };
+            }
+        }
+    }
+    return { ok: true, hosts: validatedHosts };
+}

package/dist/proxy/pairing/controller.d.ts

@@ -0,0 +1,19 @@
+import type { ProxyState } from "../core/state.js";
+import type { DiscoveryRunner } from "../discovery/runner.js";
+import type { UpstreamBridge } from "../runtime/upstream-bridge.js";
+export declare class PairingController {
+    private readonly state;
+    private readonly runner;
+    private readonly bridge;
+    private readonly log;
+    private readonly sendNotification;
+    private pairing;
+    constructor(state: ProxyState, runner: DiscoveryRunner, bridge: UpstreamBridge, log: (line: string) => void, sendNotification: (method: string) => void);
+    handleConfigure(): Promise<string>;
+    teardownPairing(): void;
+    private validateHostCreds;
+    private handleListServers;
+    private handleDiscover;
+    private handleComplete;
+    closeAllSessions(): Promise<void>;
+}

package/dist/proxy/pairing/controller.js

@@ -0,0 +1,327 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PairingController = void 0;
+const node_crypto_1 = require("node:crypto");
+const protocol_js_1 = require("../../shared/protocol.js");
+const constants_js_1 = require("../core/constants.js");
+const client_js_1 = require("../discovery/client.js");
+const config_js_1 = require("./config.js");
+const http_js_1 = require("./http.js");
+const tunnel_js_1 = require("./tunnel.js");
+const validation_js_1 = require("./validation.js");
+// Owns the pairing flow end-to-end: brings up the temporary HTTP server +
+// cloudflared tunnel, serves the setup page, mediates discovery on the
+// browser's behalf (so pairing-time and runtime use the same client
+// capabilities/clientInfo), validates the submitted config, and atomically
+// installs it into ProxyState. Also closes any prior pairing's sessions
+// before the next pairing's discovery starts.
+class PairingController {
+    state;
+    runner;
+    bridge;
+    log;
+    sendNotification;
+    pairing = null;
+    constructor(state, runner, bridge, log, sendNotification) {
+        this.state = state;
+        this.runner = runner;
+        this.bridge = bridge;
+        this.log = log;
+        this.sendNotification = sendNotification;
+    }
+    async handleConfigure() {
+        this.teardownPairing();
+        const bearer = (0, node_crypto_1.randomBytes)(32).toString("base64url");
+        const http = new http_js_1.PairingHttpServer(bearer, {
+            listServers: (req) => this.handleListServers(req),
+            discover: (req) => this.handleDiscover(req),
+            complete: (cfg) => this.handleComplete(cfg),
+            // Surface the existing PairingConfig so a reconfigure flow can
+            // pre-fill the setup page. The endpoint is already gated by the
+            // pairing bearer token, so disclosing the auth tokens here is
+            // bounded by the same trust boundary as a fresh pairing.
+            info: () => ({
+                name: protocol_js_1.PACKAGE_NAME,
+                version: protocol_js_1.PACKAGE_VERSION,
+                ...(this.state.config ? {
+                    current: {
+                        hosts: this.state.config.hosts.map((h) => ({
+                            id: h.id,
+                            tunnelUrl: h.tunnelUrl,
+                            authToken: h.authToken,
+                            ...(h.label ? { label: h.label } : {}),
+                        })),
+                        ...(this.state.config.selectedServers ? { selectedServers: [...this.state.config.selectedServers] } : {}),
+                        ...(this.state.config.selectedTools ? { selectedTools: [...this.state.config.selectedTools] } : {}),
+                    },
+                } : {}),
+            }),
+        });
+        const port = await http.listen();
+        const tunnel = new tunnel_js_1.PairingTunnel();
+        let tunnelUrl;
+        try {
+            tunnelUrl = await tunnel.start(port, (reason) => {
+                // cloudflared/wrapper died after advertising a URL. The setup link
+                // we already returned points at a dead tunnel; tear pairing down so
+                // a subsequent `configure` call can re-bootstrap instead of waiting
+                // out PAIRING_WINDOW_MS. The reason carries whatever cloudflared
+                // last reported so the operator knows whether to retry or
+                // investigate.
+                this.log(`  Pairing tunnel exited unexpectedly (${reason}); setup URL invalidated`);
+                this.teardownPairing();
+            });
+        }
+        catch (err) {
+            http.close();
+            tunnel.stop();
+            throw new Error(`Failed to start pairing tunnel: ${err.message}`);
+        }
+        // Setup page is served from the pairing tunnel itself — same origin as
+        // the /pair/* endpoints, so no CORS is involved. Token rides in the
+        // URL fragment so it never leaves the browser as Referer / origin log.
+        const setupUrl = `${tunnelUrl.replace(/\/+$/, "")}/#token=${bearer}`;
+        const expiryTimer = setTimeout(() => {
+            this.log(`  Pairing window expired (${constants_js_1.PAIRING_WINDOW_MS / 1000}s); tunnel closed`);
+            this.teardownPairing();
+        }, constants_js_1.PAIRING_WINDOW_MS);
+        expiryTimer.unref();
+        this.pairing = { tunnel, http, setupUrl, expiryTimer };
+        this.log(`\n  Configure at: ${setupUrl}\n`);
+        return `Open this URL in your browser to set up the MCP Proxy:\n\n${setupUrl}\n\nThe proxy will connect automatically once setup is complete.`;
+    }
+    teardownPairing() {
+        if (!this.pairing)
+            return;
+        const { tunnel, http, expiryTimer } = this.pairing;
+        this.pairing = null;
+        clearTimeout(expiryTimer);
+        try {
+            http.close();
+        }
+        catch { /* already closed */ }
+        try {
+            tunnel.stop();
+        }
+        catch { /* already stopped */ }
+    }
+    // Validate the host credentials the browser submitted on a /pair/* call.
+    // Single source of truth so list-servers and discover share the same
+    // gating rules — without this the two endpoints could disagree about
+    // what counts as a valid tunnel URL or what the canonicalised origin is.
+    validateHostCreds(req) {
+        if (!req.tunnelUrl || !req.authToken) {
+            return { ok: false, error: "tunnelUrl and authToken are required" };
+        }
+        const url = (0, validation_js_1.allowedTunnelUrl)(req.tunnelUrl);
+        if (!url) {
+            return {
+                ok: false,
+                error: "tunnelUrl is not on the allowlist. Use an https URL on a Cloudflare tunnel domain (.trycloudflare.com / .cfargotunnel.com), or extend MCP_TUNNEL_HOST_SUFFIXES / MCP_ALLOW_LOCAL on the proxy environment.",
+            };
+        }
+        return {
+            ok: true,
+            origin: url.origin,
+            headers: {
+                "Content-Type": "application/json",
+                Accept: "application/json, text/event-stream",
+                Authorization: `Bearer ${req.authToken}`,
+            },
+        };
+    }
+    // GET / on the host agent — list of advertised server names. Surfaces
+    // an explicit 401 status to the browser so the setup page can show
+    // "invalid auth token" rather than a generic upstream error.
+    async handleListServers(req) {
+        const v = this.validateHostCreds(req);
+        if (!v.ok)
+            return { ok: false, error: v.error, status: 400 };
+        try {
+            const servers = await (0, client_js_1.listHostServers)(v.origin, v.headers);
+            return { ok: true, servers };
+        }
+        catch (err) {
+            const msg = err.message;
+            if (msg.startsWith("list HTTP 401")) {
+                return { ok: false, error: "invalid auth token", status: 401 };
+            }
+            return { ok: false, error: msg };
+        }
+    }
+    // Per-server discovery on behalf of the setup page. Uses the captured
+    // clientCapabilities/clientInfo from the live MCP session — same values
+    // the runtime path will use — so capability-gated upstreams cannot look
+    // empty here and rich at runtime (or vice versa). Always closes the
+    // host-side session afterwards: pairing is read-only inspection, not
+    // an active session.
+    async handleDiscover(req) {
+        // Local validation failures must surface as HTTP 400, matching
+        // handleListServers — without `status` the http layer defaults to 502,
+        // which mislabels caller input errors as upstream failures and makes
+        // the two pairing endpoints disagree about the same class of problem.
+        const v = this.validateHostCreds(req);
+        if (!v.ok)
+            return { ok: false, error: v.error, status: 400 };
+        if (!req.serverName)
+            return { ok: false, error: "serverName is required", status: 400 };
+        const reason = (0, protocol_js_1.validateServerName)(req.serverName);
+        if (reason)
+            return { ok: false, error: `serverName ${reason}`, status: 400 };
+        const targetUrl = `${v.origin}/servers/${req.serverName}`;
+        let sessionId;
+        try {
+            const result = await (0, client_js_1.discoverServerCapabilities)(targetUrl, v.headers, req.serverName, this.state.clientCapabilities, this.state.clientInfo);
+            sessionId = result.sessionId;
+            const out = {
+                ok: true,
+                tools: result.tools,
+                prompts: result.prompts,
+                resources: result.resources,
+                resourceTemplates: result.resourceTemplates,
+            };
+            if (Object.keys(result.capErrors).length > 0)
+                out.capErrors = result.capErrors;
+            return out;
+        }
+        catch (err) {
+            const dErr = err;
+            sessionId = dErr.sessionId;
+            // Propagate auth failures the same way list-servers does so the UI
+            // can show "invalid auth token" instead of a generic 502. Discovery
+            // errors come from initialize / tools/list / prompts/list / etc and
+            // all spell their HTTP status as "<method> HTTP <status>: …".
+            if (/HTTP 401\b/.test(dErr.message ?? "")) {
+                return { ok: false, error: "invalid auth token", status: 401 };
+            }
+            return { ok: false, error: dErr.message };
+        }
+        finally {
+            if (sessionId) {
+                void (0, client_js_1.deleteSession)(targetUrl, { ...v.headers, "Mcp-Session-Id": sessionId });
+            }
+        }
+    }
+    async handleComplete(cfg) {
+        const validation = (0, config_js_1.validatePairingConfig)(cfg);
+        if (!validation.ok)
+            return { ok: false, error: validation.error };
+        // Snapshot the active pairing before tearing it down so we can roll
+        // back if the new pairing fails to land any server. closeAllSessions
+        // is unconditional, so without this snapshot a bad submit would leave
+        // the proxy paired-but-empty with no path back to the prior config.
+        const previousConfig = this.state.config;
+        const previousHosts = previousConfig?.hosts ?? null;
+        await this.closeAllSessions();
+        this.state.installConfig({
+            hosts: validation.hosts,
+            selectedServers: cfg.selectedServers,
+            selectedTools: cfg.selectedTools,
+            sealed: true,
+        }, validation.hosts);
+        // Wait for discovery to settle before responding so the operator
+        // gets a real success/failure signal instead of a cheerful ok on a
+        // paired-but-empty proxy. Discovery is bounded by per-host fetch
+        // timeouts; the browser is fine to wait that long.
+        await this.runner.discoverServers();
+        // Strict completion check — same rule the UI enforces at submit:
+        // every selectedServers entry must have ended up in state.hosts after
+        // discovery, otherwise we'd persist a partially broken pairing that
+        // the browser path would have rejected. Without this, a direct caller
+        // of the bearer-auth endpoint (UI gates client-side, but /pair/complete
+        // is callable directly) ends up paired with missing servers and the
+        // proxy reports `ok: true`. Mirror it server-side so behaviour is the
+        // same whichever path lands the config.
+        //
+        // selectedServers is optional in PairingConfig (allow-all). When it's
+        // omitted we can't enumerate which servers were "expected" — fall back
+        // to "every advertised host must land at least one server".
+        const missing = [];
+        if (cfg.selectedServers) {
+            // Server names may contain `__`, so prefix-match on the FIRST `__`
+            // — same parsing rule used in validatePairingConfig.
+            for (const key of cfg.selectedServers) {
+                const sep = key.indexOf("__");
+                if (sep <= 0)
+                    continue; // shape already gated by validatePairingConfig
+                const hostId = key.slice(0, sep);
+                const serverName = key.slice(sep + 2);
+                if (!this.state.hosts.get(hostId)?.servers.has(serverName)) {
+                    missing.push(key);
+                }
+            }
+        }
+        else {
+            for (const host of this.state.hosts.values()) {
+                if (host.servers.size === 0)
+                    missing.push(`${host.config.id} (no servers)`);
+            }
+        }
+        if (missing.length > 0) {
+            // Cap the detail string so a wildly broken submit doesn't produce a
+            // multi-kilobyte error body; the operator only needs a few names to
+            // know which host to investigate.
+            const detail = missing.length > 5
+                ? `${missing.slice(0, 5).join(", ")}, and ${missing.length - 5} more`
+                : missing.join(", ");
+            await this.closeAllSessions();
+            if (previousConfig && previousHosts) {
+                this.log(`  New pairing missing servers (${detail}); restoring previous pairing`);
+                this.state.installConfig(previousConfig, previousHosts);
+                await this.runner.discoverServers();
+                return {
+                    ok: false,
+                    error: `Discovery did not complete for: ${detail}. The previous pairing has been restored — verify host reachability and retry.`,
+                };
+            }
+            // First-time pairing missed servers: drop back to unconfigured
+            // (closeAllSessions cleared hosts/routes already; null the config
+            // so the next configure call starts fresh).
+            this.log(`  New pairing missing servers (${detail}) and no prior config to restore; reverting to unconfigured`);
+            this.state.config = null;
+            return {
+                ok: false,
+                error: `Discovery did not complete for: ${detail}. Verify host reachability and retry.`,
+            };
+        }
+        const summary = validation.hosts.map((h) => `${h.id}=${h.tunnelUrl}`).join(", ");
+        this.log(`  Paired! hosts: ${summary}`);
+        // Discovery already populated the aggregated lists. Notify the agent
+        // so it re-fetches tools/prompts/resources instead of trusting any
+        // cached empty lists from before pairing.
+        this.sendNotification("notifications/tools/list_changed");
+        this.sendNotification("notifications/prompts/list_changed");
+        this.sendNotification("notifications/resources/list_changed");
+        // Defer pairing teardown until /pair/complete's response body has
+        // actually drained to the client — a fixed timer races slow clients
+        // (mobile data, congested tunnel) and they see a dropped connection
+        // on a successful pair.
+        return { ok: true, afterFlush: () => this.teardownPairing() };
+    }
+    async closeAllSessions() {
+        // Tear down SSE listeners first so loops don't reconnect after DELETE.
+        for (const host of this.state.hosts.values()) {
+            for (const ctrl of host.sseControllers.values())
+                ctrl.abort();
+            host.sseControllers.clear();
+        }
+        this.state.inflight.clear();
+        this.state.progressTokens.clear();
+        // Drain bridged requests BEFORE the DELETEs below so each upstream
+        // child gets a JSON-RPC error answer. The DELETE will then reap the
+        // session, but the upstream side has already stopped waiting.
+        await this.bridge.clear(this.state.hosts);
+        const closes = [];
+        for (const host of this.state.hosts.values()) {
+            for (const [serverName, state] of host.servers) {
+                if (!state.sessionId)
+                    continue;
+                const headers = { ...this.state.hostHeaders(host.config), "Mcp-Session-Id": state.sessionId };
+                closes.push((0, client_js_1.deleteSession)(`${host.config.tunnelUrl}/servers/${serverName}`, headers));
+            }
+        }
+        await Promise.allSettled(closes);
+        this.state.resetAfterClose();
+    }
+}
+exports.PairingController = PairingController;

package/dist/proxy/pairing/http.d.ts

@@ -0,0 +1,70 @@
+import type { PairingConfig, Prompt, Resource, ResourceTemplate, Tool } from "../core/types.js";
+export interface ListServersRequest {
+    tunnelUrl: string;
+    authToken: string;
+}
+export interface ListServersResult {
+    ok: boolean;
+    servers?: string[];
+    error?: string;
+    status?: number;
+}
+export interface DiscoverServerRequest {
+    tunnelUrl: string;
+    authToken: string;
+    serverName: string;
+}
+export interface DiscoverServerResult {
+    ok: boolean;
+    tools?: Tool[];
+    prompts?: Prompt[];
+    resources?: Resource[];
+    resourceTemplates?: ResourceTemplate[];
+    capErrors?: {
+        prompts?: string;
+        resources?: string;
+        resourceTemplates?: string;
+    };
+    error?: string;
+    status?: number;
+}
+export type CompleteResult = {
+    ok: true;
+    afterFlush?: () => void;
+} | {
+    ok: false;
+    error: string;
+};
+export interface PairingHandlers {
+    listServers: (req: ListServersRequest) => Promise<ListServersResult>;
+    discover: (req: DiscoverServerRequest) => Promise<DiscoverServerResult>;
+    complete: (cfg: PairingConfig) => Promise<CompleteResult>;
+    info: () => {
+        name: string;
+        version: string;
+        current?: {
+            hosts: Array<{
+                id: string;
+                tunnelUrl: string;
+                authToken: string;
+                label?: string;
+            }>;
+            selectedServers?: string[];
+            selectedTools?: string[];
+        };
+    };
+}
+export declare class PairingHttpServer {
+    private readonly bearer;
+    private readonly handlers;
+    private server;
+    private bearerExpected;
+    constructor(bearer: string, handlers: PairingHandlers);
+    listen(): Promise<number>;
+    close(): void;
+    private authorized;
+    private sendJson;
+    private sendStatic;
+    private readJson;
+    private handle;
+}