@mcp-rating/gateway 0.2.0

package/dist/sandbox/container-runtime.js

@@ -0,0 +1,178 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { log } from "../utils/logger.js";
+const execFileAsync = promisify(execFile);
+export const DEFAULT_IMAGES = {
+    node: "node:22-alpine",
+    python: "python:3.12-slim",
+    default: "node:22-alpine",
+};
+let cachedEngine;
+/**
+ * Detect an available container engine (docker preferred, then podman).
+ * Result is cached for the process lifetime. Returns null if none is usable.
+ */
+export async function detectContainerEngine() {
+    if (cachedEngine !== undefined)
+        return cachedEngine;
+    for (const engine of ["docker", "podman"]) {
+        try {
+            await execFileAsync(engine, ["version", "--format", "{{.Client.Version}}"], {
+                timeout: 5_000,
+            });
+            log.info("Container engine detected", { engine });
+            cachedEngine = engine;
+            return engine;
+        }
+        catch {
+            // try next
+        }
+    }
+    log.warn("No container engine (docker/podman) available — L2 isolation unavailable");
+    cachedEngine = null;
+    return null;
+}
+/** Reset the cached engine (for tests). */
+export function _resetEngineCache() {
+    cachedEngine = undefined;
+}
+/** Deterministic image name for a pre-baked server image. */
+export function bakedImageName(slug) {
+    const safe = slug.replace(/[^a-z0-9_.-]/gi, "-").toLowerCase();
+    return `mcp-sandbox/${safe}:latest`;
+}
+/**
+ * Check whether a pre-baked image exists locally for this slug. A baked image
+ * has the server package installed at build time, so it runs offline under
+ * `network: none` without an npx/uvx fetch.
+ *
+ * Returns { image, bin } if present, else null.
+ */
+export async function resolveBakedImage(engine, slug) {
+    const image = bakedImageName(slug);
+    try {
+        const { stdout } = await execFileAsync(engine, ["image", "inspect", "--format", '{{index .Config.Labels "mcp.sandbox.bin"}}', image], { timeout: 5_000 });
+        const bin = stdout.trim() || null;
+        log.debug("Using pre-baked server image", { slug, image, bin });
+        return { image, bin };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Choose a base image for the given command.
+ *  - npx / npm / node / yarn / pnpm  → node image
+ *  - uvx / uv / python / python3 / pip → python image
+ *  - anything else                     → default image
+ */
+export function selectImage(command, images = DEFAULT_IMAGES) {
+    const c = command.toLowerCase().replace(/\.(exe|cmd)$/, "");
+    if (["npx", "npm", "node", "yarn", "pnpm"].includes(c))
+        return images.node;
+    if (["uvx", "uv", "python", "python3", "pip", "pip3"].includes(c))
+        return images.python;
+    return images.default;
+}
+/**
+ * Compute the run command for a pre-baked image. Runs the baked bin directly
+ * with any args that followed the package spec in the original invocation.
+ * Falls back to the original command if no bin was detected.
+ */
+function bakedRunCommand(baked, command, args) {
+    if (!baked.bin) {
+        // No bin label — best effort: run original command (may fail offline).
+        return { cmd: command, cmdArgs: args };
+    }
+    // Pass through args that came AFTER the package token. The package token is
+    // the first non-flag arg (e.g. "@scope/pkg"); npx flags like -y precede it.
+    const pkgIdx = args.findIndex((a) => !a.startsWith("-"));
+    const passThrough = pkgIdx >= 0 ? args.slice(pkgIdx + 1) : [];
+    return { cmd: baked.bin, cmdArgs: passThrough };
+}
+export function buildContainerCommand(engine, manifest, command, args, opts = {}) {
+    const images = opts.images ?? DEFAULT_IMAGES;
+    const runArgs = ["run", "--rm", "-i"];
+    // ── Hardening (always applied) ──────────────────────────────────────────
+    runArgs.push("--cap-drop", "ALL");
+    runArgs.push("--security-opt", "no-new-privileges");
+    runArgs.push("--read-only");
+    // Writable scratch space the server can always use.
+    runArgs.push("--tmpfs", "/tmp:rw,exec,nosuid,size=128m");
+    // Run as a non-root uid:gid. 1000:1000 is the conventional first user.
+    runArgs.push("--user", "1000:1000");
+    // ── Network ─────────────────────────────────────────────────────────────
+    // NOTE: "allowlist" egress filtering requires a proxy/sidecar and is not yet
+    // hard-enforced — it currently maps to the default bridge with the intent
+    // declared in the manifest. "none" and "all" are enforced.
+    switch (manifest.network.mode) {
+        case "none":
+            runArgs.push("--network", "none");
+            break;
+        case "allowlist":
+            // Route egress through the gateway's allowlist proxy. The container uses
+            // the default bridge but only proxy-aware traffic to allowlisted hosts
+            // succeeds; the host.docker.internal mapping lets it reach the proxy.
+            if (opts.egressProxyUrl) {
+                runArgs.push("--add-host", "host.docker.internal:host-gateway");
+                runArgs.push("-e", `HTTPS_PROXY=${opts.egressProxyUrl}`);
+                runArgs.push("-e", `HTTP_PROXY=${opts.egressProxyUrl}`);
+                runArgs.push("-e", `https_proxy=${opts.egressProxyUrl}`);
+                runArgs.push("-e", `http_proxy=${opts.egressProxyUrl}`);
+                // Don't proxy localhost / the proxy host itself.
+                runArgs.push("-e", "NO_PROXY=localhost,127.0.0.1");
+            }
+            break;
+        case "all":
+            // default bridge network (egress allowed).
+            break;
+    }
+    // ── Resource limits ─────────────────────────────────────────────────────
+    if (manifest.limits?.maxMemoryMb) {
+        runArgs.push("--memory", `${manifest.limits.maxMemoryMb}m`);
+    }
+    if (manifest.limits?.maxCpuPercent) {
+        const cpus = Math.max(0.1, manifest.limits.maxCpuPercent / 100);
+        runArgs.push("--cpus", cpus.toFixed(2));
+    }
+    // ── Filesystem mounts ───────────────────────────────────────────────────
+    for (const p of manifest.filesystem.read) {
+        runArgs.push("-v", `${p}:${p}:ro`);
+    }
+    for (const p of manifest.filesystem.write) {
+        runArgs.push("-v", `${p}:${p}:rw`);
+    }
+    // ── Writable cache/home redirection ─────────────────────────────────────
+    // Under --read-only root, the default HOME (/home/node, /root) and package
+    // caches (~/.npm, ~/.cache) are not writable. Redirect them to the tmpfs so
+    // npx / uvx can install the server on first run inside the sandbox.
+    runArgs.push("-e", "HOME=/tmp");
+    runArgs.push("-e", "XDG_CACHE_HOME=/tmp/.cache");
+    const image = selectImage(command, images);
+    if (image === images.python) {
+        runArgs.push("-e", "UV_CACHE_DIR=/tmp/.uv");
+        runArgs.push("-e", "PIP_CACHE_DIR=/tmp/.pip");
+    }
+    else {
+        runArgs.push("-e", "npm_config_cache=/tmp/.npm");
+    }
+    // ── Environment forwarding (names only; values come from spawn env) ──────
+    const forwardedEnvNames = [];
+    for (const name of manifest.env.allow) {
+        runArgs.push("-e", name);
+        forwardedEnvNames.push(name);
+    }
+    // ── Image + the actual server command ───────────────────────────────────
+    // A pre-baked image already contains the package, so run its bin offline.
+    if (opts.bakedImage) {
+        const { cmd, cmdArgs } = bakedRunCommand(opts.bakedImage, command, args);
+        runArgs.push(opts.bakedImage.image);
+        runArgs.push(cmd, ...cmdArgs);
+    }
+    else {
+        runArgs.push(image);
+        runArgs.push(command, ...args);
+    }
+    return { command: engine, args: runArgs, forwardedEnvNames };
+}
+//# sourceMappingURL=container-runtime.js.map

package/dist/sandbox/container-runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"container-runtime.js","sourceRoot":"","sources":["../../src/sandbox/container-runtime.ts"],"names":[],"mappings":"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"}

package/dist/sandbox/egress-proxy.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Match a "host:port" target against an allowlist pattern.
+ *
+ * Supported patterns:
+ *   - "api.github.com:443"      exact host + port
+ *   - "api.github.com"          exact host, any port
+ *   - "*.githubusercontent.com" wildcard subdomain, any port
+ *   - "*.example.com:443"       wildcard subdomain + port
+ */
+export declare function matchesAllowlist(host: string, port: number, allowlist: string[]): boolean;
+/**
+ * An in-process HTTP forward proxy that enforces a host allowlist via the
+ * CONNECT method (used by HTTPS clients). Connections to non-allowlisted
+ * hosts are refused with 403.
+ *
+ * Containerized servers are pointed at this proxy via HTTPS_PROXY/HTTP_PROXY
+ * and reach it through `host.docker.internal`. This gives `network: allowlist`
+ * real teeth without a container sidecar.
+ *
+ * Limitation: only proxy-aware clients (those honoring HTTP(S)_PROXY) are
+ * filtered. Clients that ignore proxy env vars bypass it — full enforcement
+ * still requires L2 network namespacing, but this covers the common case
+ * (node fetch/undici, axios, requests, etc. all honor the proxy env).
+ */
+export declare class EgressProxy {
+    private readonly allowlist;
+    private readonly slug;
+    /** Optional safety audit log — records blocked/allowed egress for forensics. */
+    private readonly auditLog?;
+    private server;
+    private port;
+    private blockedCount;
+    constructor(allowlist: string[], slug: string, 
+    /** Optional safety audit log — records blocked/allowed egress for forensics. */
+    auditLog?: {
+        record: (e: {
+            type: "egress_blocked" | "egress_allowed";
+            slug: string;
+            target?: string;
+            reason?: string;
+        }) => void;
+    } | undefined);
+    /** Start listening on a random loopback port. Resolves with the port. */
+    start(): Promise<number>;
+    private handleConnect;
+    /** The proxy URL the container should use (via host.docker.internal). */
+    get containerProxyUrl(): string;
+    get blocked(): number;
+    /** Stop the proxy. */
+    stop(): Promise<void>;
+}

package/dist/sandbox/egress-proxy.js

@@ -0,0 +1,146 @@
+import { createServer } from "node:http";
+import { connect as netConnect } from "node:net";
+import { log } from "../utils/logger.js";
+/**
+ * Match a "host:port" target against an allowlist pattern.
+ *
+ * Supported patterns:
+ *   - "api.github.com:443"      exact host + port
+ *   - "api.github.com"          exact host, any port
+ *   - "*.githubusercontent.com" wildcard subdomain, any port
+ *   - "*.example.com:443"       wildcard subdomain + port
+ */
+export function matchesAllowlist(host, port, allowlist) {
+    const h = host.toLowerCase();
+    for (const raw of allowlist) {
+        const pattern = raw.toLowerCase().trim();
+        if (!pattern)
+            continue;
+        const [patHost, patPort] = pattern.includes(":")
+            ? pattern.split(":")
+            : [pattern, undefined];
+        // Port check (if the pattern specified one)
+        if (patPort !== undefined && patPort !== String(port))
+            continue;
+        // Host check — exact or wildcard
+        if (patHost.startsWith("*.")) {
+            const suffix = patHost.slice(1); // ".githubusercontent.com"
+            if (h.endsWith(suffix) || h === patHost.slice(2))
+                return true;
+        }
+        else if (h === patHost) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * An in-process HTTP forward proxy that enforces a host allowlist via the
+ * CONNECT method (used by HTTPS clients). Connections to non-allowlisted
+ * hosts are refused with 403.
+ *
+ * Containerized servers are pointed at this proxy via HTTPS_PROXY/HTTP_PROXY
+ * and reach it through `host.docker.internal`. This gives `network: allowlist`
+ * real teeth without a container sidecar.
+ *
+ * Limitation: only proxy-aware clients (those honoring HTTP(S)_PROXY) are
+ * filtered. Clients that ignore proxy env vars bypass it — full enforcement
+ * still requires L2 network namespacing, but this covers the common case
+ * (node fetch/undici, axios, requests, etc. all honor the proxy env).
+ */
+export class EgressProxy {
+    allowlist;
+    slug;
+    auditLog;
+    server = null;
+    port = 0;
+    blockedCount = 0;
+    constructor(allowlist, slug, 
+    /** Optional safety audit log — records blocked/allowed egress for forensics. */
+    auditLog) {
+        this.allowlist = allowlist;
+        this.slug = slug;
+        this.auditLog = auditLog;
+    }
+    /** Start listening on a random loopback port. Resolves with the port. */
+    async start() {
+        return new Promise((resolve, reject) => {
+            const server = createServer((req, res) => {
+                // Plain HTTP proxying is not supported — only CONNECT (HTTPS tunnel).
+                // Reject non-CONNECT requests; most MCP servers use HTTPS APIs.
+                res.writeHead(405, { "Content-Type": "text/plain" });
+                res.end("Only CONNECT (HTTPS) is proxied by the gateway egress filter.\n");
+            });
+            server.on("connect", (req, clientSocket, head) => {
+                this.handleConnect(req, clientSocket, head);
+            });
+            server.on("error", (err) => reject(err));
+            // Bind to loopback only — the container reaches it via host.docker.internal,
+            // which Docker maps to the host loopback.
+            server.listen(0, "0.0.0.0", () => {
+                const addr = server.address();
+                this.port = typeof addr === "object" && addr ? addr.port : 0;
+                this.server = server;
+                log.info("Egress proxy started", {
+                    slug: this.slug,
+                    port: this.port,
+                    allowlist: this.allowlist,
+                });
+                resolve(this.port);
+            });
+        });
+    }
+    handleConnect(req, clientSocket, head) {
+        // req.url for CONNECT is "host:port"
+        const target = req.url || "";
+        const [host, portStr] = target.split(":");
+        const port = parseInt(portStr || "443", 10);
+        if (!host || !matchesAllowlist(host, port, this.allowlist)) {
+            this.blockedCount++;
+            log.warn("Egress blocked by allowlist", {
+                slug: this.slug,
+                target,
+                blockedTotal: this.blockedCount,
+            });
+            this.auditLog?.record({
+                type: "egress_blocked",
+                slug: this.slug,
+                target,
+                reason: "not in network allowlist",
+            });
+            clientSocket.write("HTTP/1.1 403 Forbidden\r\n\r\nBlocked by MCP gateway egress allowlist\r\n");
+            clientSocket.end();
+            return;
+        }
+        this.auditLog?.record({ type: "egress_allowed", slug: this.slug, target });
+        // Allowed — open the upstream tunnel and pipe bytes both ways.
+        const upstream = netConnect(port, host, () => {
+            clientSocket.write("HTTP/1.1 200 Connection Established\r\n\r\n");
+            if (head && head.length)
+                upstream.write(head);
+            upstream.pipe(clientSocket);
+            clientSocket.pipe(upstream);
+        });
+        upstream.on("error", (err) => {
+            log.debug("Egress upstream error", { slug: this.slug, target, error: String(err) });
+            clientSocket.end();
+        });
+        clientSocket.on("error", () => upstream.end());
+    }
+    /** The proxy URL the container should use (via host.docker.internal). */
+    get containerProxyUrl() {
+        return `http://host.docker.internal:${this.port}`;
+    }
+    get blocked() {
+        return this.blockedCount;
+    }
+    /** Stop the proxy. */
+    async stop() {
+        if (!this.server)
+            return;
+        await new Promise((resolve) => this.server.close(() => resolve()));
+        this.server = null;
+        log.debug("Egress proxy stopped", { slug: this.slug });
+    }
+}
+//# sourceMappingURL=egress-proxy.js.map

package/dist/sandbox/egress-proxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"egress-proxy.js","sourceRoot":"","sources":["../../src/sandbox/egress-proxy.ts"],"names":[],"mappings":"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"}

package/dist/sandbox/env-scoper.d.ts

@@ -0,0 +1,29 @@
+import type { EnvPolicy } from "./types.js";
+/**
+ * Build the scoped environment for a downstream stdio process.
+ *
+ * This is the first hard-enforced sandbox control (L1). Instead of passing the
+ * full inherited environment (which can leak API keys, cloud credentials, and
+ * tokens sitting in the parent process's env), we pass ONLY:
+ *
+ *   1. The SDK's safe default vars (PATH, HOME, etc.) — when `inheritDefaults`
+ *      is true and the process needs them to start.
+ *   2. The explicitly allowlisted var NAMES from the manifest.
+ *   3. The user-supplied env values for this connection (always honored — the
+ *      user clearly intends those to flow to this server).
+ *
+ * Everything else in `process.env` is withheld.
+ *
+ * @param policy        Env policy from the resolved capability manifest
+ * @param userEnv       Env values the user passed at connect time
+ * @param sourceEnv     The environment to scope from (defaults to process.env)
+ * @returns The scoped environment object to hand to StdioClientTransport
+ */
+export declare function buildScopedEnvironment(policy: EnvPolicy, userEnv: Record<string, string> | undefined, sourceEnv?: NodeJS.ProcessEnv): Record<string, string>;
+/**
+ * Returns the names of environment variables that WOULD have been exposed
+ * under the old "inherit everything" behavior but are now withheld. Used for
+ * surfacing the security improvement to the user / logs without ever printing
+ * the values themselves.
+ */
+export declare function withheldEnvNames(scoped: Record<string, string>, sourceEnv?: NodeJS.ProcessEnv): string[];

package/dist/sandbox/env-scoper.js

@@ -0,0 +1,60 @@
+import { getDefaultEnvironment } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { log } from "../utils/logger.js";
+/**
+ * Build the scoped environment for a downstream stdio process.
+ *
+ * This is the first hard-enforced sandbox control (L1). Instead of passing the
+ * full inherited environment (which can leak API keys, cloud credentials, and
+ * tokens sitting in the parent process's env), we pass ONLY:
+ *
+ *   1. The SDK's safe default vars (PATH, HOME, etc.) — when `inheritDefaults`
+ *      is true and the process needs them to start.
+ *   2. The explicitly allowlisted var NAMES from the manifest.
+ *   3. The user-supplied env values for this connection (always honored — the
+ *      user clearly intends those to flow to this server).
+ *
+ * Everything else in `process.env` is withheld.
+ *
+ * @param policy        Env policy from the resolved capability manifest
+ * @param userEnv       Env values the user passed at connect time
+ * @param sourceEnv     The environment to scope from (defaults to process.env)
+ * @returns The scoped environment object to hand to StdioClientTransport
+ */
+export function buildScopedEnvironment(policy, userEnv, sourceEnv = process.env) {
+    const scoped = {};
+    // 1. Safe defaults required for the process to launch (PATH, HOME, etc.)
+    if (policy.inheritDefaults) {
+        Object.assign(scoped, getDefaultEnvironment());
+    }
+    // 2. Allowlisted variable names pulled from the source environment.
+    let leakedBlocked = 0;
+    for (const name of policy.allow) {
+        const value = sourceEnv[name];
+        if (value !== undefined && !value.startsWith("()")) {
+            scoped[name] = value;
+        }
+    }
+    // 3. User-supplied env always flows (explicit intent for this connection).
+    if (userEnv) {
+        Object.assign(scoped, userEnv);
+    }
+    // Diagnostics: how many parent-env vars were withheld (not the values).
+    const withheld = Object.keys(sourceEnv).filter((k) => !(k in scoped));
+    leakedBlocked = withheld.length;
+    log.debug("Scoped downstream environment", {
+        allowed: Object.keys(scoped).length,
+        withheld: leakedBlocked,
+        inheritDefaults: policy.inheritDefaults,
+    });
+    return scoped;
+}
+/**
+ * Returns the names of environment variables that WOULD have been exposed
+ * under the old "inherit everything" behavior but are now withheld. Used for
+ * surfacing the security improvement to the user / logs without ever printing
+ * the values themselves.
+ */
+export function withheldEnvNames(scoped, sourceEnv = process.env) {
+    return Object.keys(sourceEnv).filter((k) => !(k in scoped));
+}
+//# sourceMappingURL=env-scoper.js.map

package/dist/sandbox/env-scoper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-scoper.js","sourceRoot":"","sources":["../../src/sandbox/env-scoper.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,2CAA2C,CAAC;AAClF,OAAO,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AAGzC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,sBAAsB,CACpC,MAAiB,EACjB,OAA2C,EAC3C,YAA+B,OAAO,CAAC,GAAG;IAE1C,MAAM,MAAM,GAA2B,EAAE,CAAC;IAE1C,yEAAyE;IACzE,IAAI,MAAM,CAAC,eAAe,EAAE,CAAC;QAC3B,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,qBAAqB,EAAE,CAAC,CAAC;IACjD,CAAC;IAED,oEAAoE;IACpE,IAAI,aAAa,GAAG,CAAC,CAAC;IACtB,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QAChC,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;QAC9B,IAAI,KAAK,KAAK,SAAS,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YACnD,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;QACvB,CAAC;IACH,CAAC;IAED,2EAA2E;IAC3E,IAAI,OAAO,EAAE,CAAC;QACZ,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,CAAC;IAED,wEAAwE;IACxE,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,MAAM,CAC5C,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,CACtB,CAAC;IACF,aAAa,GAAG,QAAQ,CAAC,MAAM,CAAC;IAChC,GAAG,CAAC,KAAK,CAAC,+BAA+B,EAAE;QACzC,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM;QACnC,QAAQ,EAAE,aAAa;QACvB,eAAe,EAAE,MAAM,CAAC,eAAe;KACxC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAC9B,MAA8B,EAC9B,YAA+B,OAAO,CAAC,GAAG;IAE1C,OAAO,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC;AAC9D,CAAC"}

package/dist/sandbox/manifest-resolver.d.ts

@@ -0,0 +1,40 @@
+import type { TrustTier, RegistryServer } from "../registry/types.js";
+import type { CapabilityManifest, ManifestSummary } from "./types.js";
+/**
+ * Resolves and persists per-server capability manifests.
+ *
+ * A manifest is derived from (in priority order):
+ *   1. A user-saved override (persisted to disk)
+ *   2. Trust-tier defaults + the server's declared auth env vars
+ */
+export declare class ManifestResolver {
+    private overrides;
+    private readonly filePath;
+    /**
+     * When true, untrusted tiers (community/unknown) default to l2-container
+     * enforcement instead of l1-process. Verified/trusted stay on L1.
+     */
+    private readonly containerIsolation;
+    constructor(filePath: string, containerIsolation?: boolean);
+    /**
+     * Resolve the effective manifest for a server. Uses a saved override if one
+     * exists; otherwise derives defaults from the trust tier and the server's
+     * declared auth env vars (so e.g. a GitHub server gets GITHUB_TOKEN allowed
+     * but nothing else).
+     */
+    resolve(slug: string, trustTier: TrustTier, registryServer?: RegistryServer | null, 
+    /** Env var names the user explicitly supplied at connect time. */
+    userProvidedEnvKeys?: string[]): CapabilityManifest;
+    /** Get a saved override for a slug, if one exists. */
+    getOverride(slug: string): CapabilityManifest | undefined;
+    /** Persist a user-customized manifest. */
+    saveOverride(manifest: CapabilityManifest): void;
+    /** Remove a saved override, reverting to trust-tier defaults. */
+    clearOverride(slug: string): void;
+    /**
+     * Build a human-readable summary of a manifest for the HITL prompt.
+     */
+    static summarize(manifest: CapabilityManifest): ManifestSummary;
+    private loadFromDisk;
+    private saveToDisk;
+}