mcptrustchecker 1.0.0

package/dist/acquire/index.d.ts

@@ -0,0 +1,24 @@
+/*! MCP Trust Checker · https://mcptrustchecker.com · support@mcptrustchecker.com · © 2026 Illia Haidar · MIT */
+/**
+ * Target resolution — turn a CLI target (path / URL / package / config) plus
+ * options into one or more normalized surfaces, choosing the safest acquisition
+ * path. Live process spawning from a client config is opt-in (`--run`).
+ */
+import type { ServerSurface } from '../types.js';
+import { type LiveOptions } from './live.js';
+export interface ResolveOptions extends LiveOptions {
+    command?: string;
+    args?: string[];
+    url?: string;
+    online?: boolean;
+    run?: boolean;
+    registry?: 'npm' | 'pypi';
+    /** Environment variables to pass to a `--command` stdio server. */
+    envVars?: Record<string, string>;
+}
+export interface ResolvedTarget {
+    label: string;
+    surface: ServerSurface;
+}
+/** Resolve a target into scannable surfaces. */
+export declare function resolveTargets(target: string | undefined, opts?: ResolveOptions): Promise<ResolvedTarget[]>;

package/dist/acquire/index.js

@@ -0,0 +1,175 @@
+/*! MCP Trust Checker · https://mcptrustchecker.com · support@mcptrustchecker.com · © 2026 Illia Haidar · MIT */
+/**
+ * Target resolution — turn a CLI target (path / URL / package / config) plus
+ * options into one or more normalized surfaces, choosing the safest acquisition
+ * path. Live process spawning from a client config is opt-in (`--run`).
+ */
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { surfaceFromManifest } from './manifest.js';
+import { surfaceFromPackageDir } from './source.js';
+import { acquireHttp, acquireStdio, ALLOWED_COMMANDS } from './live.js';
+import { expandVars, isClientConfig, packageSpecFromStdio, parseClientConfig, redactSensitiveArgs, } from './clientConfig.js';
+import { fetchNpmMeta, fetchPypiMeta } from './npm.js';
+const NPM_NAME = /^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/i;
+const HTTP_RE = /^https?:\/\//i;
+function commandBase(command) {
+    const cleaned = command.replace(/\\/g, '/');
+    return cleaned.slice(cleaned.lastIndexOf('/') + 1);
+}
+async function metaFor(name, opts) {
+    if (!opts.online)
+        return { registry: opts.registry ?? 'npm', name };
+    return opts.registry === 'pypi' ? fetchPypiMeta(name) : fetchNpmMeta(name);
+}
+function packageSurface(name, meta, origin) {
+    return {
+        id: name,
+        source: { kind: 'package', origin },
+        server: { name },
+        tools: [],
+        prompts: [],
+        resources: [],
+        packageMeta: meta,
+    };
+}
+/** Strip the query string from a stored URL so config-embedded tokens don't leak. */
+function redactUrl(url) {
+    if (!url)
+        return url;
+    try {
+        const u = new URL(url);
+        if (u.search)
+            u.search = ''; // query-string tokens
+        u.username = ''; // userinfo credentials (user:pass@host)
+        u.password = '';
+        return u.href;
+    }
+    catch {
+        return url;
+    }
+}
+/** Build the static (no-spawn) surface for one client-config server entry. */
+function staticConfigSurface(spec, origin) {
+    const transport = spec.transport === 'http'
+        ? { kind: 'http', url: redactUrl(spec.url) }
+        : {
+            kind: 'stdio',
+            command: spec.command,
+            args: redactSensitiveArgs(spec.args ?? []),
+            // A path-qualified command OR one outside the allowlist is untrusted.
+            userControlledCommand: spec.command
+                ? /[\\/]/.test(spec.command) || !ALLOWED_COMMANDS.has(commandBase(spec.command))
+                : false,
+        };
+    return {
+        id: spec.id,
+        source: { kind: 'client-config', origin },
+        server: { name: spec.id },
+        tools: [],
+        prompts: [],
+        resources: [],
+        transport,
+    };
+}
+/** Resolve a target into scannable surfaces. */
+export async function resolveTargets(target, opts = {}) {
+    // 1) Explicit live specs win.
+    if (opts.command) {
+        const surface = await acquireStdio({ command: opts.command, args: opts.args, env: opts.envVars }, opts);
+        return [{ label: surface.id, surface }];
+    }
+    if (opts.url || (target && HTTP_RE.test(target))) {
+        const url = opts.url ?? target;
+        const surface = await acquireHttp(url, opts);
+        return [{ label: url, surface }];
+    }
+    if (!target)
+        throw new Error('No scan target provided.');
+    // A scoped npm/PyPI package (@scope/name) contains '/' but is NOT a path.
+    const isScopedPkg = /^@[a-z0-9-~][a-z0-9-._~]*\/[a-z0-9-~][a-z0-9-._~]*$/i.test(target);
+    const looksLikePath = !isScopedPkg && (target.includes('/') || target.includes('\\') || target.toLowerCase().endsWith('.json'));
+    // A path/manifest target that doesn't exist: say so plainly.
+    if (looksLikePath && !existsSync(target)) {
+        throw new Error(`No such file: ${target}`);
+    }
+    // A local package DIRECTORY → analyze its implementation source + metadata.
+    if (existsSync(target) && statSync(target).isDirectory()) {
+        return [{ label: target, surface: surfaceFromPackageDir(target) }];
+    }
+    // 2) A file on disk: manifest or client config.
+    if (existsSync(target) && target.toLowerCase().endsWith('.json')) {
+        let json;
+        try {
+            json = JSON.parse(readFileSync(target, 'utf8'));
+        }
+        catch (err) {
+            throw new Error(`Invalid JSON in ${target}: ${err.message}`);
+        }
+        if (isClientConfig(json)) {
+            const specs = parseClientConfig(json);
+            const results = [];
+            for (const spec of specs) {
+                if (opts.run) {
+                    // URLs/commands come from an UNTRUSTED config. Expand ${VAR} ONLY from
+                    // the entry's own env block — NEVER from the scanner's process.env,
+                    // which would leak operator secrets into an outbound request.
+                    const varEnv = { ...(spec.env ?? {}) };
+                    try {
+                        const surface = spec.transport === 'http'
+                            ? await acquireHttp(expandVars(spec.url, varEnv), { ...opts, blockPrivateHosts: opts.blockPrivateHosts ?? true })
+                            : await acquireStdio({
+                                command: expandVars(spec.command, varEnv),
+                                args: (spec.args ?? []).map((a) => expandVars(a, varEnv)),
+                                env: spec.env,
+                            }, opts);
+                        // Use the config's server key as the stable id (not the raw command,
+                        // which may embed a token), and scrub any secrets from stored args.
+                        surface.id = spec.id;
+                        surface.source = { kind: 'client-config', origin: target };
+                        if (surface.transport?.args)
+                            surface.transport.args = redactSensitiveArgs(surface.transport.args);
+                        // The expanded URL can carry a ${TOKEN} in its query/userinfo — redact
+                        // it before it is stored in the report (matches the static path).
+                        if (surface.transport?.url)
+                            surface.transport.url = redactUrl(surface.transport.url) ?? surface.transport.url;
+                        results.push({ label: spec.id, surface });
+                    }
+                    catch {
+                        // One dead/unreachable server must not abort the whole config scan.
+                        results.push({ label: spec.id, surface: staticConfigSurface(spec, target) });
+                    }
+                    continue;
+                }
+                // Static: posture + supply-chain only, no process spawned.
+                const surface = staticConfigSurface(spec, target);
+                if (spec.transport === 'stdio' && spec.command) {
+                    const pkgSpec = packageSpecFromStdio(spec.command, spec.args ?? []);
+                    // Only fetch metadata for a well-formed package name (config values are untrusted).
+                    if (pkgSpec && NPM_NAME.test(pkgSpec.name)) {
+                        const meta = await metaFor(pkgSpec.name, opts);
+                        meta.requestedSpec = pkgSpec.version;
+                        meta.pinned = Boolean(pkgSpec.version && pkgSpec.version !== 'latest' && /^[0-9]/.test(pkgSpec.version));
+                        surface.packageMeta = meta;
+                    }
+                }
+                results.push({ label: spec.id, surface });
+            }
+            if (results.length === 0)
+                throw new Error(`No MCP servers found in config: ${target}`);
+            return results;
+        }
+        // Plain tools manifest — must be a JSON object, not an array/null/scalar.
+        if (!json || typeof json !== 'object' || Array.isArray(json)) {
+            throw new Error(`${target} is not a recognizable MCP manifest (expected a JSON object with a "tools" array or an "mcpServers" map).`);
+        }
+        const surface = surfaceFromManifest(json, target);
+        return [{ label: surface.id, surface }];
+    }
+    // 3) A bare package name → supply-chain / provenance scan.
+    if (NPM_NAME.test(target)) {
+        const meta = await metaFor(target, opts);
+        return [{ label: target, surface: packageSurface(target, meta, target) }];
+    }
+    throw new Error(`Could not resolve target "${target}". Provide a tools.json manifest, an http(s) URL, ` +
+        `a client config, a package name, or use --command for stdio.`);
+}

package/dist/acquire/live.d.ts

@@ -0,0 +1,47 @@
+/*! MCP Trust Checker · https://mcptrustchecker.com · support@mcptrustchecker.com · © 2026 Illia Haidar · MIT */
+/**
+ * Live acquisition over the wire using the official MCP SDK.
+ *
+ * SECURITY: scanning is itself an attack surface. stdio acquisition spawns a
+ * child process, so we:
+ *   - allowlist the executable by BARE NAME only (a path like `/tmp/node`
+ *     is rejected — a basename must not authorize an attacker-chosen path);
+ *   - pass a scrubbed environment: the parent env is not inherited by us, and
+ *     any caller/config-supplied env has execution-hijacking variables
+ *     (NODE_OPTIONS, LD_PRELOAD, DYLD_*, PYTHON*, …) stripped, so an allowlisted
+ *     runtime can't be redirected;  (the SDK still injects a small sudo-style
+ *     safe subset — HOME/PATH/SHELL/TERM/USER — via getDefaultEnvironment());
+ *   - capture stderr and enforce aggressive timeouts.
+ * HTTP acquisition validates the URL scheme, and — for config-derived URLs —
+ * blocks private/loopback/link-local hosts to prevent SSRF.
+ *
+ * The SDK is imported dynamically so the pure engine and its tests never need
+ * it loaded; live scanning requires `@modelcontextprotocol/sdk` at runtime.
+ */
+import type { ServerSurface } from '../types.js';
+/** Executables permitted for stdio acquisition (the canonical safe set). */
+export declare const ALLOWED_COMMANDS: Set<string>;
+/** Drop execution-hijacking vars and bash function definitions from an env map. */
+export declare function sanitizeEnv(env: Record<string, string>): {
+    clean: Record<string, string>;
+    dropped: string[];
+};
+export declare function isBlockedHost(hostname: string): boolean;
+export interface StdioSpec {
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+}
+export interface LiveOptions {
+    /** Allow spawning a command outside the allowlist (opt-in, dangerous). */
+    allowAnyCommand?: boolean;
+    /** Restrict HTTP acquisition to these hostnames. */
+    allowedHosts?: string[];
+    /** Block private/loopback/link-local hosts (set for untrusted, config-derived URLs). */
+    blockPrivateHosts?: boolean;
+}
+/** Acquire a surface by spawning a local stdio MCP server. */
+export declare function acquireStdio(spec: StdioSpec, opts?: LiveOptions): Promise<ServerSurface>;
+/** Acquire a surface from a Streamable-HTTP / SSE endpoint. */
+export declare function acquireHttp(url: string, opts?: LiveOptions): Promise<ServerSurface>;

package/dist/acquire/live.js

@@ -0,0 +1,357 @@
+/*! MCP Trust Checker · https://mcptrustchecker.com · support@mcptrustchecker.com · © 2026 Illia Haidar · MIT */
+/**
+ * Live acquisition over the wire using the official MCP SDK.
+ *
+ * SECURITY: scanning is itself an attack surface. stdio acquisition spawns a
+ * child process, so we:
+ *   - allowlist the executable by BARE NAME only (a path like `/tmp/node`
+ *     is rejected — a basename must not authorize an attacker-chosen path);
+ *   - pass a scrubbed environment: the parent env is not inherited by us, and
+ *     any caller/config-supplied env has execution-hijacking variables
+ *     (NODE_OPTIONS, LD_PRELOAD, DYLD_*, PYTHON*, …) stripped, so an allowlisted
+ *     runtime can't be redirected;  (the SDK still injects a small sudo-style
+ *     safe subset — HOME/PATH/SHELL/TERM/USER — via getDefaultEnvironment());
+ *   - capture stderr and enforce aggressive timeouts.
+ * HTTP acquisition validates the URL scheme, and — for config-derived URLs —
+ * blocks private/loopback/link-local hosts to prevent SSRF.
+ *
+ * The SDK is imported dynamically so the pure engine and its tests never need
+ * it loaded; live scanning requires `@modelcontextprotocol/sdk` at runtime.
+ */
+import { surfaceFromManifest } from './manifest.js';
+/** Executables permitted for stdio acquisition (the canonical safe set). */
+export const ALLOWED_COMMANDS = new Set(['npx', 'uvx', 'python', 'python3', 'node', 'docker', 'deno']);
+/**
+ * Environment variables that can hijack an otherwise-trusted runtime. Stripped
+ * from any caller/config-supplied env before spawning, so an allowlisted
+ * `node`/`python` can't be told to load attacker code at startup.
+ */
+const DANGEROUS_ENV_EXACT = new Set([
+    'PATH', // a config-supplied PATH would redirect an allowlisted `node`/`python` to an attacker binary
+    'NODE_PATH', // hijacks bare-import resolution for `node`
+    'NODE_OPTIONS',
+    'NODE_REPL_EXTERNAL_MODULE',
+    'PYTHONSTARTUP',
+    'PYTHONPATH',
+    'PYTHONHOME',
+    'PERL5OPT',
+    'RUBYOPT',
+    'BASH_ENV',
+    'ENV',
+    'GIT_SSH_COMMAND',
+    'GIT_EXTERNAL_DIFF',
+    // Package-index redirects — a config env could point `npx`/`uvx`/`pip` at an
+    // attacker-controlled registry (supply-chain redirect). Defense-in-depth.
+    'NPM_CONFIG_REGISTRY',
+    'PIP_INDEX_URL',
+    'PIP_EXTRA_INDEX_URL',
+    'UV_INDEX_URL',
+    'UV_DEFAULT_INDEX',
+]);
+const DANGEROUS_ENV_PREFIX = ['LD_', 'DYLD_', 'NPM_CONFIG_'];
+/** Drop execution-hijacking vars and bash function definitions from an env map. */
+export function sanitizeEnv(env) {
+    const clean = {};
+    const dropped = [];
+    for (const [k, v] of Object.entries(env)) {
+        const key = k.toUpperCase();
+        const bad = DANGEROUS_ENV_EXACT.has(key) ||
+            DANGEROUS_ENV_PREFIX.some((p) => key.startsWith(p)) ||
+            (typeof v === 'string' && v.startsWith('()'));
+        if (bad)
+            dropped.push(k);
+        else
+            clean[k] = v;
+    }
+    return { clean, dropped };
+}
+/** True for a private/loopback/link-local IPv4 dotted-quad. */
+function isPrivateIpv4(h) {
+    const m = h.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+    if (!m)
+        return false;
+    const a = Number(m[1]);
+    const b = Number(m[2]);
+    return (a === 127 || a === 10 || a === 0 ||
+        (a === 192 && b === 168) ||
+        (a === 172 && b >= 16 && b <= 31) ||
+        (a === 169 && b === 254) // link-local incl. cloud metadata 169.254.169.254
+    );
+}
+/**
+ * Block loopback / private / link-local hosts (SSRF guard for config-derived
+ * URLs). IPv6 checks apply only to actual IPv6 literals (so DNS names like
+ * "fc-api.com" aren't blocked), and IPv4-mapped IPv6 (::ffff:127.0.0.1) is
+ * unwrapped. NOTE: this is string-based; a public DNS name that *resolves* to a
+ * private IP (DNS rebinding) is not caught here — that is inherent to pre-connect
+ * static checks and is documented as out of scope.
+ */
+/**
+ * Extract the embedded IPv4 of an IPv4-mapped IPv6 literal. Node's URL parser
+ * normalizes `::ffff:169.254.169.254` to the HEX form `::ffff:a9fe:a9fe`, so we
+ * must accept BOTH the dotted and the hextet forms — the previous dotted-only
+ * regex was dead code against a real `URL.hostname`, leaving cloud-metadata
+ * (169.254.169.254) reachable through the SSRF guard.
+ */
+function mappedIpv4(h) {
+    const dotted = h.match(/:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);
+    if (dotted)
+        return dotted[1];
+    const hex = h.match(/::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+    if (hex) {
+        const hi = parseInt(hex[1], 16);
+        const lo = parseInt(hex[2], 16);
+        return `${(hi >> 8) & 255}.${hi & 255}.${(lo >> 8) & 255}.${lo & 255}`;
+    }
+    return undefined;
+}
+export function isBlockedHost(hostname) {
+    // Strip brackets and a trailing FQDN dot (`localhost.` resolves like `localhost`).
+    const h = hostname.toLowerCase().replace(/^\[|\]$/g, '').replace(/\.$/, '');
+    if (h === 'localhost' || h.endsWith('.localhost'))
+        return true;
+    if (isPrivateIpv4(h))
+        return true;
+    // IPv6 literal (contains a colon)
+    if (h.includes(':')) {
+        if (h === '::1' || h === '::')
+            return true;
+        if (h.startsWith('fe80:') || h.startsWith('fc') || h.startsWith('fd'))
+            return true; // link-local / ULA
+        const embedded = mappedIpv4(h);
+        if (embedded && isPrivateIpv4(embedded))
+            return true; // IPv4-mapped IPv6 (dotted OR hextet form)
+    }
+    return false;
+}
+const REQUEST_OPTS = { timeout: 15_000, maxTotalTimeout: 30_000, resetTimeoutOnProgress: false };
+const CONNECT_TIMEOUT_MS = 20_000;
+const MAX_ITEMS = 1000;
+const MAX_PAGES = 50;
+function withTimeout(p, ms, label) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms);
+        p.then((v) => {
+            clearTimeout(timer);
+            resolve(v);
+        }, (e) => {
+            clearTimeout(timer);
+            reject(e);
+        });
+    });
+}
+/* eslint-disable @typescript-eslint/no-explicit-any */
+async function loadSdk() {
+    try {
+        const [{ Client }, stdio, http, sse] = await Promise.all([
+            import('@modelcontextprotocol/sdk/client/index.js'),
+            import('@modelcontextprotocol/sdk/client/stdio.js'),
+            import('@modelcontextprotocol/sdk/client/streamableHttp.js'),
+            import('@modelcontextprotocol/sdk/client/sse.js'),
+        ]);
+        return {
+            Client,
+            StdioClientTransport: stdio.StdioClientTransport,
+            StreamableHTTPClientTransport: http.StreamableHTTPClientTransport,
+            SSEClientTransport: sse.SSEClientTransport,
+        };
+    }
+    catch (err) {
+        throw new Error('Live scanning requires the "@modelcontextprotocol/sdk" package. ' +
+            `Install it (npm i @modelcontextprotocol/sdk). Underlying error: ${err.message}`);
+    }
+}
+// Permissive result schemas so a single non-spec-compliant tool/prompt/resource
+// object does not make the SDK reject the WHOLE list (real servers are often
+// slightly non-compliant — scanning them is exactly the point). Built once from
+// the zod that ships with the SDK; falls back to the strict high-level calls.
+let looseSchemas;
+async function getLooseSchemas() {
+    if (looseSchemas !== undefined)
+        return looseSchemas ?? null;
+    try {
+        const zod = await import('zod');
+        const z = zod.z ?? zod.default ?? zod;
+        const mk = (key) => z.object({ [key]: z.array(z.any()).optional(), nextCursor: z.string().optional() }).passthrough();
+        looseSchemas = { tools: mk('tools'), prompts: mk('prompts'), resources: mk('resources') };
+    }
+    catch {
+        looseSchemas = null;
+    }
+    return looseSchemas;
+}
+async function listLoose(client, method, key, cursor) {
+    const schemas = await getLooseSchemas();
+    const params = cursor ? { cursor } : {};
+    if (schemas && typeof client.request === 'function') {
+        const r = await client.request({ method, params }, schemas[key], REQUEST_OPTS);
+        return { items: Array.isArray(r?.[key]) ? r[key] : [], nextCursor: r?.nextCursor };
+    }
+    const fn = key === 'tools' ? 'listTools' : key === 'prompts' ? 'listPrompts' : 'listResources';
+    const r = await client[fn](params, REQUEST_OPTS);
+    return { items: Array.isArray(r?.[key]) ? r[key] : [], nextCursor: r?.nextCursor };
+}
+async function enumerate(client) {
+    const caps = client.getServerCapabilities?.() ?? {};
+    const info = client.getServerVersion?.() ?? {};
+    const instructions = client.getInstructions?.();
+    const tools = [];
+    let cursor;
+    let pages = 0;
+    do {
+        const r = await listLoose(client, 'tools/list', 'tools', cursor);
+        for (const t of r.items)
+            tools.push(t);
+        cursor = r.nextCursor;
+        // Bound BOTH item count and page count: a malicious server can return
+        // empty pages with a persistent cursor forever.
+        if (tools.length >= MAX_ITEMS || ++pages >= MAX_PAGES)
+            break;
+    } while (cursor);
+    const prompts = [];
+    if (caps.prompts) {
+        try {
+            const r = await listLoose(client, 'prompts/list', 'prompts');
+            for (const p of r.items)
+                prompts.push(p);
+        }
+        catch {
+            /* optional capability */
+        }
+    }
+    const resources = [];
+    if (caps.resources) {
+        try {
+            const r = await listLoose(client, 'resources/list', 'resources');
+            for (const res of r.items)
+                resources.push(res);
+        }
+        catch {
+            /* optional capability */
+        }
+    }
+    return {
+        tools,
+        prompts,
+        resources,
+        server: {
+            name: info.name,
+            version: info.version,
+            title: info.title,
+            instructions,
+            capabilities: caps,
+        },
+    };
+}
+function commandBase(command) {
+    const cleaned = command.replace(/\\/g, '/');
+    return cleaned.slice(cleaned.lastIndexOf('/') + 1);
+}
+/** Acquire a surface by spawning a local stdio MCP server. */
+export async function acquireStdio(spec, opts = {}) {
+    const base = commandBase(spec.command);
+    // A path separator means the caller specified an explicit path; a basename
+    // match must NOT authorize an attacker-chosen path (e.g. /tmp/evil/node).
+    const hasPathSeparator = /[\\/]/.test(spec.command);
+    const allowed = ALLOWED_COMMANDS.has(base) && !hasPathSeparator;
+    if (!allowed && !opts.allowAnyCommand) {
+        const reason = hasPathSeparator
+            ? `path-qualified commands are not allowlisted (only bare names ${[...ALLOWED_COMMANDS].join(', ')})`
+            : `not in the executable allowlist (${[...ALLOWED_COMMANDS].join(', ')})`;
+        throw new Error(`Refusing to spawn "${spec.command}": ${reason}. Re-run with --allow-any-command only if you trust it.`);
+    }
+    const { clean: safeEnv, dropped } = sanitizeEnv(spec.env ?? {});
+    const sdk = await loadSdk();
+    const transport = new sdk.StdioClientTransport({
+        command: spec.command,
+        args: spec.args ?? [],
+        // PATH last so a (scrubbed, but defense-in-depth) config env can never win.
+        env: { ...safeEnv, PATH: process.env.PATH ?? '' },
+        cwd: spec.cwd ?? process.cwd(),
+        stderr: 'pipe',
+    });
+    const client = new sdk.Client({ name: 'mcptrustchecker', version: '1.0.0' }, { capabilities: {} });
+    try {
+        await withTimeout(client.connect(transport), CONNECT_TIMEOUT_MS, 'stdio connect');
+        const enumd = await enumerate(client);
+        const id = `${spec.command} ${(spec.args ?? []).join(' ')}`.trim();
+        const surface = surfaceFromManifest({ ...enumd }, id, id);
+        surface.source = { kind: 'stdio', origin: id };
+        surface.transport = {
+            kind: 'stdio',
+            command: spec.command,
+            args: spec.args ?? [],
+            userControlledCommand: !allowed,
+            ...(dropped.length ? { droppedEnv: dropped } : {}),
+        };
+        return surface;
+    }
+    finally {
+        await client.close?.().catch(() => { });
+    }
+}
+/** Acquire a surface from a Streamable-HTTP / SSE endpoint. */
+export async function acquireHttp(url, opts = {}) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error(`Invalid URL: ${url}`);
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        throw new Error(`Unsupported URL scheme "${parsed.protocol}" (only http/https).`);
+    }
+    if (opts.allowedHosts && !opts.allowedHosts.includes(parsed.hostname)) {
+        throw new Error(`Host ${parsed.hostname} is not in the allowed-hosts list.`);
+    }
+    if (opts.blockPrivateHosts && isBlockedHost(parsed.hostname)) {
+        throw new Error(`Refusing to connect to private/loopback host "${parsed.hostname}" from an untrusted config (SSRF guard). ` +
+            `Use --allowed-hosts to permit specific hosts.`);
+    }
+    const sdk = await loadSdk();
+    const client = new sdk.Client({ name: 'mcptrustchecker', version: '1.0.0' }, { capabilities: {} });
+    // Re-validate every redirect hop: the initial-URL SSRF check is useless if the
+    // server 302s to http://[::ffff:169.254.169.254]/. We follow redirects
+    // manually (capped) and run each hop's host back through the same guard.
+    const guardedFetch = async (input, init) => {
+        let current = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+        for (let hop = 0; hop < 6; hop++) {
+            const res = await fetch(current, { ...init, redirect: 'manual' });
+            const loc = res.status >= 300 && res.status < 400 ? res.headers.get('location') : null;
+            if (!loc)
+                return res;
+            const next = new URL(loc, current);
+            if (next.protocol !== 'http:' && next.protocol !== 'https:')
+                throw new Error(`Blocked redirect to non-http scheme "${next.protocol}".`);
+            if (opts.allowedHosts && !opts.allowedHosts.includes(next.hostname))
+                throw new Error(`Blocked redirect to disallowed host "${next.hostname}".`);
+            if (opts.blockPrivateHosts && isBlockedHost(next.hostname))
+                throw new Error(`SSRF: blocked redirect to private/loopback host "${next.hostname}".`);
+            current = next.href;
+        }
+        throw new Error('Too many redirects.');
+    };
+    const connect = async () => {
+        try {
+            const t = new sdk.StreamableHTTPClientTransport(parsed, { fetch: guardedFetch });
+            await withTimeout(client.connect(t), CONNECT_TIMEOUT_MS, 'http connect');
+        }
+        catch {
+            const sseT = new sdk.SSEClientTransport(parsed, { fetch: guardedFetch });
+            await withTimeout(client.connect(sseT), CONNECT_TIMEOUT_MS, 'sse connect');
+        }
+    };
+    try {
+        await connect();
+        const enumd = await enumerate(client);
+        const surface = surfaceFromManifest({ ...enumd }, url, url);
+        surface.source = { kind: 'http', origin: url };
+        surface.transport = { kind: 'http', url };
+        return surface;
+    }
+    finally {
+        await client.close?.().catch(() => { });
+    }
+}
+/* eslint-enable @typescript-eslint/no-explicit-any */

package/dist/acquire/manifest.d.ts

@@ -0,0 +1,10 @@
+/*! MCP Trust Checker · https://mcptrustchecker.com · support@mcptrustchecker.com · © 2026 Illia Haidar · MIT */
+/**
+ * Offline acquisition: build a normalized ServerSurface from a pre-generated
+ * JSON manifest. Accepts several shapes so `mcptrustchecker scan tools.json` "just
+ * works": a raw `tools/list` result, a full surface object, or a hand-written
+ * `{ server, tools, prompts, resources }`.
+ */
+import type { ServerSurface } from '../types.js';
+/** Build a surface from an arbitrary manifest object. */
+export declare function surfaceFromManifest(input: unknown, origin: string, id?: string): ServerSurface;