mcptrustchecker 1.0.0 → 1.2.0

package/dist/acquire/live.js

@@ -19,6 +19,8 @@
  * it loaded; live scanning requires `@modelcontextprotocol/sdk` at runtime.
  */
 import { surfaceFromManifest } from './manifest.js';
+import { TOOL_VERSION } from '../version.js';
+import { applyCredentialGate } from '../util/headers.js';
 /** Executables permitted for stdio acquisition (the canonical safe set). */
 export const ALLOWED_COMMANDS = new Set(['npx', 'uvx', 'python', 'python3', 'node', 'docker', 'deno']);
 /**
@@ -143,17 +145,19 @@ function withTimeout(p, ms, label) {
 /* eslint-disable @typescript-eslint/no-explicit-any */
 async function loadSdk() {
     try {
-        const [{ Client }, stdio, http, sse] = await Promise.all([
+        const [{ Client }, stdio, http, sse, auth] = 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'),
+            import('@modelcontextprotocol/sdk/client/auth.js'),
         ]);
         return {
             Client,
             StdioClientTransport: stdio.StdioClientTransport,
             StreamableHTTPClientTransport: http.StreamableHTTPClientTransport,
             SSEClientTransport: sse.SSEClientTransport,
+            UnauthorizedError: auth.UnauthorizedError,
         };
     }
     catch (err) {
@@ -270,7 +274,7 @@ export async function acquireStdio(spec, opts = {}) {
         cwd: spec.cwd ?? process.cwd(),
         stderr: 'pipe',
     });
-    const client = new sdk.Client({ name: 'mcptrustchecker', version: '1.0.0' }, { capabilities: {} });
+    const client = new sdk.Client({ name: 'mcptrustchecker', version: TOOL_VERSION }, { capabilities: {} });
     try {
         await withTimeout(client.connect(transport), CONNECT_TIMEOUT_MS, 'stdio connect');
         const enumd = await enumerate(client);
@@ -310,25 +314,42 @@ export async function acquireHttp(url, opts = {}) {
             `Use --allowed-hosts to permit specific hosts.`);
     }
     const sdk = await loadSdk();
-    const client = new sdk.Client({ name: 'mcptrustchecker', version: '1.0.0' }, { capabilities: {} });
+    const client = new sdk.Client({ name: 'mcptrustchecker', version: TOOL_VERSION }, { 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.
+    // Re-validate every hop AND contain credentials. The SDK routes ALL its
+    // requests — including OAuth discovery / registration / token endpoints, whose
+    // hosts come from the *server's* metadata — through this fetch, so every hop
+    // (not just 3xx targets) must pass the SSRF guard, and credentials must never
+    // cross to a different origin.
     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' });
+            let cur;
+            try {
+                cur = new URL(current);
+            }
+            catch {
+                throw new Error(`Invalid request URL "${current}".`);
+            }
+            // SSRF guard on THIS hop's host — covers the initial request too, not just
+            // redirect targets (an OAuth authorization-server host is server-chosen).
+            if (cur.protocol !== 'http:' && cur.protocol !== 'https:')
+                throw new Error(`Blocked request to non-http scheme "${cur.protocol}".`);
+            if (opts.allowedHosts && !opts.allowedHosts.includes(cur.hostname))
+                throw new Error(`Blocked request to disallowed host "${cur.hostname}".`);
+            if (opts.blockPrivateHosts && isBlockedHost(cur.hostname))
+                throw new Error(`SSRF: blocked request to private/loopback host "${cur.hostname}".`);
+            // Credentials (the SDK-injected OAuth bearer in init.headers, and any
+            // static --header) go ONLY to the exact target ORIGIN; stripped on any
+            // cross-origin hop (redirect, downgrade, different port).
+            const headers = applyCredentialGate(init?.headers, cur.origin === parsed.origin, opts.headers);
+            const res = await fetch(current, { ...init, headers, 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;
+            current = new URL(loc, current).href;
         }
         throw new Error('Too many redirects.');
     };
@@ -342,8 +363,58 @@ export async function acquireHttp(url, opts = {}) {
             await withTimeout(client.connect(sseT), CONNECT_TIMEOUT_MS, 'sse connect');
         }
     };
+    // Interactive OAuth: register a client, open the browser, catch the redirect,
+    // exchange the code for a token, then reconnect authenticated.
+    const connectWithOAuth = async () => {
+        const { CliOAuthProvider, startCallbackServer, openBrowser } = await import('./oauth.js');
+        const cb = await startCallbackServer();
+        // Flips true the instant the browser sign-in is triggered. After that, a
+        // failure (denied consent, callback timeout, token-exchange error) is NOT a
+        // transport mismatch — we must not restart the flow on SSE (a second browser
+        // window + reuse of the already-settled single-shot callback promise).
+        let authStarted = false;
+        const provider = new CliOAuthProvider(cb.redirectUrl, opts.scope, (authUrl) => {
+            authStarted = true;
+            process.stderr.write(`\n${'→'} This MCP server requires sign-in. Opening your browser…\n` +
+                `  If it doesn't open, paste this URL:\n  ${authUrl.href}\n\n`);
+            openBrowser(authUrl.href);
+        }, cb.state);
+        const attempt = async (TransportCtor) => {
+            let transport = new TransportCtor(parsed, { authProvider: provider, fetch: guardedFetch });
+            try {
+                await withTimeout(client.connect(transport), CONNECT_TIMEOUT_MS, 'oauth connect');
+            }
+            catch (err) {
+                if (sdk.UnauthorizedError && err instanceof sdk.UnauthorizedError) {
+                    const code = await cb.waitForCode();
+                    await transport.finishAuth(code);
+                    transport = new TransportCtor(parsed, { authProvider: provider, fetch: guardedFetch });
+                    await withTimeout(client.connect(transport), CONNECT_TIMEOUT_MS, 'oauth reconnect');
+                }
+                else {
+                    throw err;
+                }
+            }
+        };
+        try {
+            try {
+                await attempt(sdk.StreamableHTTPClientTransport);
+            }
+            catch (primary) {
+                // Fall back to SSE ONLY for a pre-auth transport/protocol mismatch; once
+                // the browser has opened, surface the real error instead of re-running
+                // the whole sign-in on a second transport.
+                if (authStarted || (sdk.UnauthorizedError && primary instanceof sdk.UnauthorizedError))
+                    throw primary;
+                await attempt(sdk.SSEClientTransport);
+            }
+        }
+        finally {
+            cb.close();
+        }
+    };
     try {
-        await connect();
+        await (opts.login ? connectWithOAuth() : connect());
         const enumd = await enumerate(client);
         const surface = surfaceFromManifest({ ...enumd }, url, url);
         surface.source = { kind: 'http', origin: url };

package/dist/acquire/npm.d.ts

@@ -4,7 +4,15 @@
  * access is opt-in (`--online`); everything degrades gracefully offline.
  */
 import type { PackageMeta } from '../types.js';
-/** Fetch npm registry metadata for a package (latest dist-tag). */
-export declare function fetchNpmMeta(name: string): Promise<PackageMeta>;
-/** Fetch PyPI metadata for a package. */
-export declare function fetchPypiMeta(name: string): Promise<PackageMeta>;
+/**
+ * Fetch npm registry metadata for a package. Resolves `requested` when it names
+ * an exact published version (so a pinned `pkg@1.0.0` is analyzed, not `latest`);
+ * otherwise falls back to the `latest` dist-tag.
+ */
+export declare function fetchNpmMeta(name: string, requested?: string): Promise<PackageMeta>;
+/**
+ * Fetch PyPI metadata for a package. When `requested` is an exact version, the
+ * versioned JSON endpoint (`/pypi/<name>/<version>/json`) is used so a pinned
+ * spec is analyzed rather than the newest release.
+ */
+export declare function fetchPypiMeta(name: string, requested?: string): Promise<PackageMeta>;

package/dist/acquire/npm.js

@@ -19,14 +19,47 @@ async function getJson(url, timeoutMs = 8000) {
         clearTimeout(timer);
     }
 }
-/** Fetch npm registry metadata for a package (latest dist-tag). */
-export async function fetchNpmMeta(name) {
+/** Is `v` an exact version (not a range/tag) we can resolve to one artifact? */
+function isExactVersion(v) {
+    return typeof v === 'string' && /^\d+\.\d+\.\d+/.test(v);
+}
+/**
+ * Fetch npm registry metadata for a package. Resolves `requested` when it names
+ * an exact published version (so a pinned `pkg@1.0.0` is analyzed, not `latest`);
+ * otherwise falls back to the `latest` dist-tag.
+ */
+export async function fetchNpmMeta(name, requested) {
     const meta = { registry: 'npm', name };
     const packument = (await getJson(`https://registry.npmjs.org/${encodeURIComponent(name).replace('%40', '@')}`));
     if (packument && typeof packument === 'object') {
-        const latest = packument['dist-tags']?.latest;
-        const version = latest ?? Object.keys(packument.versions ?? {}).pop();
+        // `dist-tags.latest` is attacker-controlled: accept it ONLY as a string, so a
+        // non-primitive (array/object) can't become `meta.version`. A non-string
+        // version survives to the lockfile as `["1.0.0"]`, and after the JSON
+        // round-trip the `meta.version === entry.packageVersion` check can never be
+        // true — silently suppressing the MTC-TOFU-002 byte-level rug-pull finding.
+        const latest = typeof packument['dist-tags']?.latest === 'string' ? packument['dist-tags'].latest : undefined;
+        // `versions` is attacker-controlled; guard the `in` check so a non-object
+        // (string/number) can't throw a raw TypeError. On the client-config path an
+        // unguarded throw would unwind resolveTargets and make the CLI skip the whole
+        // config — hiding every sibling server. Fail closed instead.
+        const versions = packument.versions && typeof packument.versions === 'object' && !Array.isArray(packument.versions)
+            ? packument.versions // eslint-disable-line @typescript-eslint/no-explicit-any
+            : {};
+        // A pinned exact version that the registry does NOT list must NEVER silently
+        // fall back to `latest` — an attacker who controls the registry response
+        // could drop the pinned version and serve a malicious `latest`, defeating the
+        // byte pin (the requested version's artifact simply isn't resolved, and the
+        // substitution is flagged so it can't pass as a clean scan of the pin).
+        const wantExact = isExactVersion(requested);
+        const requestedMissing = wantExact && !Object.prototype.hasOwnProperty.call(versions, requested);
+        const version = wantExact ? requested : (latest ?? Object.keys(versions).pop());
         meta.version = version;
+        if (requestedMissing) {
+            meta.requestedVersionMissing = true;
+            // Leave scripts/deps/artifact unresolved: there is no such published
+            // version to read. tarballUrl stays undefined → no source fetch / byte pin.
+            return meta;
+        }
         const v = version ? packument.versions?.[version] : undefined;
         if (v) {
             meta.scripts = v.scripts ?? {};
@@ -34,6 +67,14 @@ export async function fetchNpmMeta(name) {
             meta.license = typeof v.license === 'string' ? v.license : v.license == null ? null : String(v.license);
             const repo = v.repository;
             meta.repositoryUrl = typeof repo === 'string' ? repo : repo?.url ?? null;
+            // The published artifact: URL + registry-declared hash (SRI, or legacy sha1 hex).
+            meta.tarballUrl = typeof v.dist?.tarball === 'string' ? v.dist.tarball : null;
+            meta.tarballIntegrity =
+                typeof v.dist?.integrity === 'string'
+                    ? v.dist.integrity
+                    : typeof v.dist?.shasum === 'string'
+                        ? `sha1:${v.dist.shasum}`
+                        : null;
         }
         meta.publishedAt = version ? packument.time?.[version] ?? null : null;
     }
@@ -42,14 +83,45 @@ export async function fetchNpmMeta(name) {
     meta.weeklyDownloads = downloads?.downloads ?? null;
     return meta;
 }
-/** Fetch PyPI metadata for a package. */
-export async function fetchPypiMeta(name) {
+/**
+ * Fetch PyPI metadata for a package. When `requested` is an exact version, the
+ * versioned JSON endpoint (`/pypi/<name>/<version>/json`) is used so a pinned
+ * spec is analyzed rather than the newest release.
+ */
+export async function fetchPypiMeta(name, requested) {
     const meta = { registry: 'pypi', name };
-    const data = (await getJson(`https://pypi.org/pypi/${encodeURIComponent(name)}/json`));
+    const url = isExactVersion(requested)
+        ? `https://pypi.org/pypi/${encodeURIComponent(name)}/${encodeURIComponent(requested)}/json`
+        : `https://pypi.org/pypi/${encodeURIComponent(name)}/json`;
+    const data = (await getJson(url));
     if (data?.info) {
-        meta.version = data.info.version;
+        // For an exact pin the version-specific endpoint is authoritative for the
+        // version, so force the label to the REQUESTED version — never let an
+        // attacker-controlled `info.version` relabel the pin to a different release
+        // (the same silent-substitution hole the npm path refuses).
+        meta.version = isExactVersion(requested)
+            ? requested
+            : typeof data.info.version === 'string'
+                ? data.info.version
+                : undefined;
         meta.license = data.info.license || null;
         meta.repositoryUrl = data.info.project_urls?.Source ?? data.info.home_page ?? null;
+        // The published artifact: prefer the sdist (real source layout) over a wheel.
+        const files = Array.isArray(data.urls) ? data.urls : [];
+        const artifact = files.find((f) => f?.packagetype === 'sdist' && typeof f.url === 'string') ??
+            files.find((f) => f?.packagetype === 'bdist_wheel' && typeof f.url === 'string');
+        if (artifact) {
+            meta.tarballUrl = artifact.url;
+            meta.tarballIntegrity =
+                typeof artifact.digests?.sha256 === 'string' ? `sha256:${artifact.digests.sha256}` : null;
+            meta.publishedAt = typeof artifact.upload_time_iso_8601 === 'string' ? artifact.upload_time_iso_8601 : null;
+        }
+    }
+    else if (isExactVersion(requested)) {
+        // The exact version endpoint returned nothing: the pinned version is not
+        // resolvable (unpublished/yanked/hidden). Flag it rather than falling back.
+        meta.version = requested;
+        meta.requestedVersionMissing = true;
     }
     return meta;
 }

package/dist/acquire/oauth.d.ts

@@ -0,0 +1,49 @@
+import type { OAuthClientProvider } from '@modelcontextprotocol/sdk/client/auth.js';
+import type { OAuthClientMetadata, OAuthTokens, OAuthClientInformationFull } from '@modelcontextprotocol/sdk/shared/auth.js';
+/** How long to wait for the user to finish signing in in their browser. */
+export declare const OAUTH_CALLBACK_TIMEOUT_MS = 180000;
+/** Open a URL in the user's default browser (best-effort, cross-platform). */
+export declare function openBrowser(url: string): void;
+/** Parse an OAuth redirect request URL into a code (+ state), or a descriptive error. */
+export declare function parseCallback(reqUrl: string | undefined): {
+    code?: string;
+    state?: string;
+    error?: Error;
+};
+export interface CallbackServer {
+    /** The loopback redirect URI to register and redirect back to. */
+    redirectUrl: string;
+    /** The CSRF `state` value the authorization request must echo back. */
+    state: string;
+    /** Resolves with the authorization code once the browser redirects back. */
+    waitForCode(): Promise<string>;
+    /** Shut the loopback server down. */
+    close(): void;
+}
+/** Start a loopback HTTP server on a free port to receive the OAuth redirect. */
+export declare function startCallbackServer(): Promise<CallbackServer>;
+/**
+ * In-memory `OAuthClientProvider`. Holds the dynamically-registered client,
+ * tokens and PKCE verifier for a single scan; opens the browser on redirect.
+ */
+export declare class CliOAuthProvider implements OAuthClientProvider {
+    private readonly _redirectUrl;
+    private readonly _scope;
+    private readonly _onAuthorize;
+    private readonly _state;
+    private _clientInformation?;
+    private _tokens?;
+    private _codeVerifier?;
+    constructor(_redirectUrl: string, _scope: string | undefined, _onAuthorize: (url: URL) => void, _state: string);
+    get redirectUrl(): string;
+    /** CSRF nonce echoed through the authorization request (OAuth 2.1 hardening). */
+    state(): string;
+    get clientMetadata(): OAuthClientMetadata;
+    clientInformation(): OAuthClientInformationFull | undefined;
+    saveClientInformation(info: OAuthClientInformationFull): void;
+    tokens(): OAuthTokens | undefined;
+    saveTokens(tokens: OAuthTokens): void;
+    redirectToAuthorization(authorizationUrl: URL): void;
+    saveCodeVerifier(codeVerifier: string): void;
+    codeVerifier(): string;
+}

package/dist/acquire/oauth.js

@@ -0,0 +1,190 @@
+/*! MCP Trust Checker · https://mcptrustchecker.com · support@mcptrustchecker.com · © 2026 Illia Haidar · MIT */
+/**
+ * Interactive OAuth 2.0 login for scanning protected remote MCP servers.
+ *
+ * Modern remote MCP servers gate their `/mcp` endpoint behind OAuth (the MCP
+ * authorization spec: discovery → dynamic client registration → authorization-
+ * code + PKCE). A static header can't authenticate there. This implements the
+ * client half of that flow for the CLI: a loopback callback server catches the
+ * redirect, the browser is opened for the user's sign-in, and the SDK exchanges
+ * the code for an access token — which it then attaches to the MCP handshake.
+ *
+ * Tokens are held in memory for the duration of one scan only — nothing is
+ * written to disk, consistent with the tool's local-first, no-account stance.
+ */
+import { createServer } from 'node:http';
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+const CLIENT_NAME = 'MCP Trust Checker';
+/** How long to wait for the user to finish signing in in their browser. */
+export const OAUTH_CALLBACK_TIMEOUT_MS = 180_000;
+/** Open a URL in the user's default browser (best-effort, cross-platform). */
+export function openBrowser(url) {
+    const [cmd, args] = process.platform === 'darwin'
+        ? ['open', [url]]
+        : process.platform === 'win32'
+            ? ['cmd', ['/c', 'start', '', url]]
+            : ['xdg-open', [url]];
+    try {
+        const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
+        child.on('error', () => {
+            /* the URL is also printed, so the user can open it manually */
+        });
+        child.unref();
+    }
+    catch {
+        /* ignore — non-fatal, the URL is printed for manual use */
+    }
+}
+/** Parse an OAuth redirect request URL into a code (+ state), or a descriptive error. */
+export function parseCallback(reqUrl) {
+    const parsed = new URL(reqUrl || '', 'http://127.0.0.1');
+    const code = parsed.searchParams.get('code');
+    const state = parsed.searchParams.get('state') || undefined;
+    if (code)
+        return { code, state };
+    const error = parsed.searchParams.get('error');
+    if (error) {
+        const desc = parsed.searchParams.get('error_description');
+        return { error: new Error(`OAuth authorization failed: ${error}${desc ? ` — ${desc}` : ''}`) };
+    }
+    return { error: new Error('OAuth callback carried no authorization code.') };
+}
+const OK_PAGE = '<!doctype html><meta charset="utf-8"><title>Authorized</title>' +
+    '<body style="font-family:system-ui,sans-serif;background:#07080b;color:#eef1f6;text-align:center;padding:64px 24px">' +
+    '<h1 style="color:#c4f542">✓ Authorized</h1>' +
+    '<p>You can close this tab and return to the terminal.</p>' +
+    '<script>setTimeout(function(){window.close()},1500)</script></body>';
+/** Start a loopback HTTP server on a free port to receive the OAuth redirect. */
+export async function startCallbackServer() {
+    let resolveCode;
+    let rejectCode;
+    const codePromise = new Promise((res, rej) => {
+        resolveCode = res;
+        rejectCode = rej;
+    });
+    const expectedState = randomUUID();
+    const server = createServer((req, res) => {
+        const parsed = new URL(req.url || '', 'http://127.0.0.1');
+        if (parsed.pathname !== '/callback') {
+            res.writeHead(404);
+            res.end();
+            return;
+        }
+        const { code, state, error } = parseCallback(req.url);
+        // Require the CSRF state to match before settling — a stray/forged local
+        // request (or a page spraying the ephemeral port) can neither complete NOR
+        // abort the sign-in.
+        if (state !== expectedState) {
+            res.writeHead(400, { 'content-type': 'text/html' });
+            res.end('<!doctype html><meta charset="utf-8"><body>Invalid OAuth state.</body>');
+            return;
+        }
+        if (code) {
+            res.writeHead(200, { 'content-type': 'text/html' });
+            res.end(OK_PAGE);
+            resolveCode(code);
+        }
+        else {
+            res.writeHead(400, { 'content-type': 'text/html' });
+            res.end(`<!doctype html><meta charset="utf-8"><body>${error.message}</body>`);
+            rejectCode(error);
+        }
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', () => {
+            server.off('error', reject);
+            resolve();
+        });
+    });
+    const addr = server.address();
+    const port = typeof addr === 'object' && addr ? addr.port : 0;
+    const redirectUrl = `http://127.0.0.1:${port}/callback`;
+    // Race the callback against a timeout, but ALWAYS clear the timer once the
+    // code arrives — a lingering setTimeout would keep the event loop (and the
+    // whole CLI, after the scan finishes) alive until it fires.
+    const waitForCode = () => new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error('Timed out waiting for the browser sign-in (3 min). Re-run to try again.')), OAUTH_CALLBACK_TIMEOUT_MS);
+        timer.unref?.();
+        codePromise.then((code) => {
+            clearTimeout(timer);
+            resolve(code);
+        }, (err) => {
+            clearTimeout(timer);
+            reject(err);
+        });
+    });
+    return {
+        redirectUrl,
+        state: expectedState,
+        waitForCode,
+        close: () => {
+            try {
+                server.close();
+            }
+            catch {
+                /* already closed */
+            }
+        },
+    };
+}
+/**
+ * In-memory `OAuthClientProvider`. Holds the dynamically-registered client,
+ * tokens and PKCE verifier for a single scan; opens the browser on redirect.
+ */
+export class CliOAuthProvider {
+    _redirectUrl;
+    _scope;
+    _onAuthorize;
+    _state;
+    _clientInformation;
+    _tokens;
+    _codeVerifier;
+    constructor(_redirectUrl, _scope, _onAuthorize, _state) {
+        this._redirectUrl = _redirectUrl;
+        this._scope = _scope;
+        this._onAuthorize = _onAuthorize;
+        this._state = _state;
+    }
+    get redirectUrl() {
+        return this._redirectUrl;
+    }
+    /** CSRF nonce echoed through the authorization request (OAuth 2.1 hardening). */
+    state() {
+        return this._state;
+    }
+    get clientMetadata() {
+        return {
+            client_name: CLIENT_NAME,
+            redirect_uris: [this._redirectUrl],
+            grant_types: ['authorization_code', 'refresh_token'],
+            response_types: ['code'],
+            token_endpoint_auth_method: 'client_secret_post',
+            ...(this._scope ? { scope: this._scope } : {}),
+        };
+    }
+    clientInformation() {
+        return this._clientInformation;
+    }
+    saveClientInformation(info) {
+        this._clientInformation = info;
+    }
+    tokens() {
+        return this._tokens;
+    }
+    saveTokens(tokens) {
+        this._tokens = tokens;
+    }
+    redirectToAuthorization(authorizationUrl) {
+        this._onAuthorize(authorizationUrl);
+    }
+    saveCodeVerifier(codeVerifier) {
+        this._codeVerifier = codeVerifier;
+    }
+    codeVerifier() {
+        if (!this._codeVerifier)
+            throw new Error('No PKCE code verifier saved.');
+        return this._codeVerifier;
+    }
+}

package/dist/acquire/packageSource.d.ts

@@ -0,0 +1,68 @@
+/*! MCP Trust Checker · https://mcptrustchecker.com · support@mcptrustchecker.com · © 2026 Illia Haidar · MIT */
+/**
+ * Read the *published bytes* of a registry package — fetch the npm/PyPI
+ * artifact, verify it against the registry-declared hash, and extract its
+ * implementation source in memory. This is what turns a bare-package scan from
+ * a metadata check into a real source-level analysis: the same MTC-SRC engine
+ * that runs on a local directory runs on the exact tarball users install.
+ *
+ * Security posture:
+ *   - network only in `--online` mode, and only to the registry's own artifact
+ *     host (allowlisted per registry) over https;
+ *   - the download is size-capped and integrity-verified BEFORE it is parsed —
+ *     a mismatched hash aborts the source read;
+ *   - nothing is written to disk and nothing is executed;
+ *   - the verified artifact's SHA-256 is recorded so the lockfile can pin the
+ *     actual bytes (same version + different bytes on rescan = rug-pull signal).
+ */
+import type { PackageMeta, ServerSurface, SourceFile } from '../types.js';
+export interface PackageSourceResult {
+    sourceFiles: SourceFile[];
+    /** Root-level sidecar files (package.json, tools.json, …) by base name. */
+    sidecars: Record<string, string>;
+    /** SHA-256 (hex) of the verified compressed artifact. */
+    tarballSha256: string;
+}
+/**
+ * Error kinds for a failed source read, so the caller can tell a SECURITY
+ * failure (bytes don't match the registry's declared hash, or the download was
+ * redirected off the allowlisted host — hard evidence of tampering) apart from
+ * a transient network failure (which must not be reported as an attack, but
+ * also must not silently pass off as "verified").
+ */
+export type PackageSourceErrorKind = 'integrity' | 'untrusted-redirect' | 'network' | 'other';
+export declare class PackageSourceError extends Error {
+    readonly kind: PackageSourceErrorKind;
+    constructor(kind: PackageSourceErrorKind, message: string);
+}
+/** Validate that an artifact URL is https on the registry's own artifact host. */
+export declare function assertTrustedTarballUrl(url: string, registry: 'npm' | 'pypi'): URL;
+/**
+ * Verify a downloaded artifact against the registry-declared hash. Accepts SRI
+ * (`sha512-<base64>`, `sha1-<base64>`) and `<algo>:<hex>` forms. Fails closed:
+ * a declared hash that can't be parsed or doesn't match rejects the artifact.
+ * `null`/absent means the registry declared none — the artifact is still used
+ * (its own SHA-256 becomes the lockfile pin), which is the TOFU trade-off.
+ */
+export declare function verifyTarballIntegrity(buf: Buffer, expected: string | null | undefined): void;
+/**
+ * Download with a hard byte cap enforced while streaming, and a timeout.
+ * Redirects are followed MANUALLY (cap 5) and every hop is re-validated through
+ * the same host allowlist — otherwise a 3xx from the registry could point the
+ * scanner at an arbitrary host (SSRF), and its bytes would be scanned and pinned
+ * as if they were the published source. Mirrors live.ts's guardedFetch posture.
+ */
+export declare function downloadCapped(url: URL, registry: 'npm' | 'pypi', fetchImpl?: typeof fetch): Promise<Buffer>;
+/**
+ * Fetch, verify and extract the published source of a registry package.
+ * Throws a descriptive error on any trust failure (bad host, over-cap, hash
+ * mismatch); returns `null` when the metadata has no artifact URL to read.
+ */
+export declare function fetchPackageSource(meta: PackageMeta, fetchImpl?: typeof fetch): Promise<PackageSourceResult | null>;
+/**
+ * Build a scan surface from a local packed artifact (.tgz / .tar.gz / .tar /
+ * .zip / .whl) — the file a release pipeline actually ships. Reads the
+ * implementation source and any package.json / sidecar manifest it contains;
+ * never writes to disk, never executes anything.
+ */
+export declare function surfaceFromArchiveFile(path: string): ServerSurface;