mcptrustchecker 1.1.0 → 1.2.0

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/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;

package/dist/acquire/packageSource.js

@@ -0,0 +1,258 @@
+/*! 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 { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { SOURCE_EXTENSIONS } from '../data/sourcePatterns.js';
+import { extractArchive, stripCommonRoot } from './archive.js';
+import { packageMetaFromJson, SIDECAR_MANIFESTS, SOURCE_LIMITS } from './source.js';
+import { surfaceFromManifest } from './manifest.js';
+import { isBlockedHost } from './live.js';
+/** Compressed-artifact download cap. */
+const MAX_DOWNLOAD_BYTES = 50 * 1024 * 1024; // 50 MB
+const DOWNLOAD_TIMEOUT_MS = 30_000;
+/**
+ * Hosts a registry is allowed to serve artifacts from. The tarball URL comes
+ * from the registry response, so we pin it to the registry's own artifact CDN —
+ * a compromised or spoofed metadata response can't point the scanner at an
+ * arbitrary server.
+ */
+const TARBALL_HOSTS = {
+    npm: ['registry.npmjs.org'],
+    pypi: ['files.pythonhosted.org'],
+};
+export class PackageSourceError extends Error {
+    kind;
+    constructor(kind, message) {
+        super(message);
+        this.name = 'PackageSourceError';
+        this.kind = kind;
+    }
+}
+/** Validate that an artifact URL is https on the registry's own artifact host. */
+export function assertTrustedTarballUrl(url, registry) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new PackageSourceError('untrusted-redirect', `invalid artifact URL "${url}"`);
+    }
+    if (parsed.protocol !== 'https:')
+        throw new PackageSourceError('untrusted-redirect', `artifact URL must be https (got ${parsed.protocol}//)`);
+    if (!TARBALL_HOSTS[registry].includes(parsed.hostname) || isBlockedHost(parsed.hostname)) {
+        throw new PackageSourceError('untrusted-redirect', `artifact host "${parsed.hostname}" is not the ${registry} registry's artifact host (${TARBALL_HOSTS[registry].join(', ')}) — refusing to fetch`);
+    }
+    return parsed;
+}
+/**
+ * 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 function verifyTarballIntegrity(buf, expected) {
+    if (!expected)
+        return;
+    let algo;
+    let digest;
+    let encoding;
+    const sri = expected.match(/^([a-z0-9]+)-([A-Za-z0-9+/=]+)$/);
+    const hexForm = expected.match(/^([a-z0-9]+):([0-9a-f]+)$/i);
+    if (sri) {
+        algo = sri[1];
+        digest = sri[2];
+        encoding = 'base64';
+    }
+    else if (hexForm) {
+        algo = hexForm[1].toLowerCase();
+        digest = hexForm[2].toLowerCase();
+        encoding = 'hex';
+    }
+    else {
+        throw new PackageSourceError('integrity', `unparseable integrity value "${expected.slice(0, 40)}" — refusing the artifact`);
+    }
+    let actual;
+    try {
+        actual = createHash(algo).update(buf).digest(encoding);
+    }
+    catch {
+        throw new PackageSourceError('integrity', `unsupported integrity algorithm "${algo}" — refusing the artifact`);
+    }
+    const normActual = encoding === 'hex' ? actual.toLowerCase() : actual;
+    if (normActual !== digest) {
+        throw new PackageSourceError('integrity', `artifact integrity mismatch: registry declared ${algo} ${digest.slice(0, 16)}… but the download hashed to ${normActual.slice(0, 16)}…`);
+    }
+}
+/**
+ * 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 async function downloadCapped(url, registry, fetchImpl = fetch) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), DOWNLOAD_TIMEOUT_MS);
+    try {
+        let current = assertTrustedTarballUrl(url.href, registry);
+        let res;
+        for (let hop = 0; hop < 6; hop++) {
+            res = await fetchImpl(current, {
+                signal: ctrl.signal,
+                redirect: 'manual',
+                headers: { 'User-Agent': 'mcptrustchecker' },
+            });
+            if (res.status >= 300 && res.status < 400) {
+                const loc = res.headers.get('location');
+                if (!loc)
+                    throw new PackageSourceError('network', `artifact redirect (${res.status}) without a Location header`);
+                // Re-run the redirect target through the full host allowlist.
+                current = assertTrustedTarballUrl(new URL(loc, current).href, registry);
+                continue;
+            }
+            break;
+        }
+        if (!res)
+            throw new PackageSourceError('network', 'artifact download produced no response');
+        if (res.status >= 300 && res.status < 400)
+            throw new PackageSourceError('network', 'too many artifact redirects');
+        if (!res.ok)
+            throw new PackageSourceError('network', `artifact download failed: HTTP ${res.status}`);
+        const declared = Number(res.headers.get('content-length') ?? 0);
+        if (declared > MAX_DOWNLOAD_BYTES) {
+            throw new PackageSourceError('network', `artifact is ${Math.round(declared / 1024 / 1024)} MB — over the ${MAX_DOWNLOAD_BYTES / 1024 / 1024} MB safety cap`);
+        }
+        if (!res.body)
+            throw new PackageSourceError('network', 'artifact download returned no body');
+        const reader = res.body.getReader();
+        const chunks = [];
+        let total = 0;
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            total += value.byteLength;
+            if (total > MAX_DOWNLOAD_BYTES) {
+                ctrl.abort();
+                throw new PackageSourceError('network', `artifact exceeded the ${MAX_DOWNLOAD_BYTES / 1024 / 1024} MB download cap`);
+            }
+            chunks.push(Buffer.from(value));
+        }
+        return Buffer.concat(chunks);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+const SIDECAR_NAMES = new Set(['package.json', ...SIDECAR_MANIFESTS]);
+/**
+ * Directories skipped inside a published artifact. Deliberately NARROWER than
+ * the local-directory skip list: a repo checkout is scanned via its authored
+ * source (dist/ is a build product to skip), but a published tarball often
+ * ships ONLY dist/ — those compiled bytes ARE what `npx` runs, so they must be
+ * read, not skipped.
+ */
+const ARCHIVE_SKIP_DIRS = new Set(['node_modules', '.git', 'coverage', '__pycache__', 'venv', '.venv', 'vendor']);
+function isSourcePath(path) {
+    const parts = path.split('/');
+    if (parts.some((p) => ARCHIVE_SKIP_DIRS.has(p)))
+        return false;
+    const base = parts[parts.length - 1];
+    const dot = base.lastIndexOf('.');
+    const ext = dot >= 0 ? base.slice(dot).toLowerCase() : '';
+    return SOURCE_EXTENSIONS.has(ext);
+}
+/**
+ * Split extracted entries into implementation source and root-level sidecars.
+ * `stripCommonRoot` unwraps a SINGLE shared top directory (npm's `package/`, a
+ * PyPI sdist's `name-version/`, a GitHub source-zip's `repo-main/`) and leaves
+ * multi-root archives (wheels: `pkg/` + `pkg.dist-info/`) untouched — so a
+ * root-level `package.json`/`tools.json` is found in every real layout. Output
+ * is sorted by path so the scan is byte-identical regardless of archive order.
+ */
+function classifyEntries(entries) {
+    const sourceFiles = [];
+    const sidecars = {};
+    for (const e of stripCommonRoot(entries)) {
+        if (!e.path.includes('/') && SIDECAR_NAMES.has(e.path))
+            sidecars[e.path] = e.data.toString('utf8');
+        if (isSourcePath(e.path))
+            sourceFiles.push({ path: e.path, content: e.data.toString('utf8') });
+    }
+    // Code-unit sort (never localeCompare) so order is reproducible on every machine.
+    sourceFiles.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    return { sourceFiles, sidecars };
+}
+/** The extraction predicate: implementation source + shallow sidecar files. */
+function wantedEntry(path) {
+    const parts = path.split('/');
+    // Sidecars only at the archive root or one level down (the pre-strip root dir).
+    if (parts.length <= 2 && SIDECAR_NAMES.has(parts[parts.length - 1]))
+        return true;
+    return isSourcePath(path);
+}
+/**
+ * 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 async function fetchPackageSource(meta, fetchImpl = fetch) {
+    if (!meta.tarballUrl)
+        return null;
+    const registry = meta.registry === 'pypi' ? 'pypi' : 'npm';
+    const url = assertTrustedTarballUrl(meta.tarballUrl, registry);
+    const buf = await downloadCapped(url, registry, fetchImpl);
+    verifyTarballIntegrity(buf, meta.tarballIntegrity);
+    const tarballSha256 = createHash('sha256').update(buf).digest('hex');
+    const entries = extractArchive(buf, url.pathname, wantedEntry, SOURCE_LIMITS);
+    return { ...classifyEntries(entries), tarballSha256 };
+}
+/**
+ * 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 function surfaceFromArchiveFile(path) {
+    const buf = readFileSync(path);
+    const entries = extractArchive(buf, path, wantedEntry, SOURCE_LIMITS);
+    const { sourceFiles, sidecars } = classifyEntries(entries);
+    let manifest = {};
+    for (const name of SIDECAR_MANIFESTS) {
+        if (sidecars[name]) {
+            try {
+                manifest = JSON.parse(sidecars[name]);
+            }
+            catch {
+                /* ignore an unparseable sidecar manifest */
+            }
+            break;
+        }
+    }
+    const surface = surfaceFromManifest(manifest, path, path);
+    surface.source = { kind: 'package', origin: path };
+    const fromPkg = sidecars['package.json'] ? packageMetaFromJson(sidecars['package.json']) : undefined;
+    surface.packageMeta = {
+        ...(fromPkg ?? { registry: 'unknown' }),
+        ...(surface.packageMeta ?? {}),
+        tarballSha256: createHash('sha256').update(buf).digest('hex'),
+    };
+    surface.sourceFiles = sourceFiles;
+    return surface;
+}

package/dist/acquire/source.d.ts

@@ -6,11 +6,21 @@
  * scan, and never executes any of the code it reads. Offline.
  */
 import type { ServerSurface, SourceFile } from '../types.js';
+export declare const SKIP_DIRS: Set<string>;
+export declare const SOURCE_LIMITS: {
+    readonly maxFiles: 400;
+    readonly maxFileBytes: number;
+    readonly maxTotalBytes: number;
+};
 /** Recursively collect scannable source files from a directory (bounded). */
 export declare function readSourceFiles(dir: string): SourceFile[];
+/** Parse a package.json's text into the surface's package metadata. */
+export declare function packageMetaFromJson(text: string): ServerSurface['packageMeta'];
 /**
  * Build a scan surface from a local package directory: its implementation source
  * (for MTC-SRC-* analysis), its package metadata (for supply-chain checks), and
  * a tools manifest if the directory ships one (tools.json / mcp-tools.json).
  */
+/** Sidecar manifest file names a package may ship, in priority order. */
+export declare const SIDECAR_MANIFESTS: readonly ["tools.json", "mcp-tools.json", "mcp.json"];
 export declare function surfaceFromPackageDir(dir: string): ServerSurface;

package/dist/acquire/source.js

@@ -9,10 +9,15 @@ import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { join, relative, extname } from 'node:path';
 import { SOURCE_EXTENSIONS } from '../data/sourcePatterns.js';
 import { surfaceFromManifest } from './manifest.js';
-const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', 'coverage', '.next', '__pycache__', 'venv', '.venv', 'vendor']);
-const MAX_FILES = 400;
-const MAX_FILE_BYTES = 512 * 1024; // 512 KB per file
-const MAX_TOTAL_BYTES = 12 * 1024 * 1024; // 12 MB total
+export const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', 'coverage', '.next', '__pycache__', 'venv', '.venv', 'vendor']);
+export const SOURCE_LIMITS = {
+    maxFiles: 400,
+    maxFileBytes: 512 * 1024, // 512 KB per file
+    maxTotalBytes: 12 * 1024 * 1024, // 12 MB total
+};
+const MAX_FILES = SOURCE_LIMITS.maxFiles;
+const MAX_FILE_BYTES = SOURCE_LIMITS.maxFileBytes;
+const MAX_TOTAL_BYTES = SOURCE_LIMITS.maxTotalBytes;
 /** Recursively collect scannable source files from a directory (bounded). */
 export function readSourceFiles(dir) {
     const out = [];
@@ -57,15 +62,19 @@ export function readSourceFiles(dir) {
         }
     };
     walk(dir);
+    // `readdirSync` returns filesystem-defined order (APFS vs ext4 differ), and the
+    // source detector caps findings per rule — so WITHOUT a stable sort the same
+    // package could yield different findings on two machines. Code-unit sort keeps
+    // the scan byte-reproducible everywhere (matches util/hash.ts's ordering rule).
+    out.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
     return out;
 }
-/** Read a package.json (if present) into the surface's package metadata. */
-function readPackageMeta(dir) {
-    const pkgPath = join(dir, 'package.json');
-    if (!existsSync(pkgPath))
-        return undefined;
+/** Parse a package.json's text into the surface's package metadata. */
+export function packageMetaFromJson(text) {
     try {
-        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+        const pkg = JSON.parse(text);
+        if (!pkg || typeof pkg !== 'object' || Array.isArray(pkg))
+            return undefined;
         return {
             registry: 'npm',
             name: typeof pkg.name === 'string' ? pkg.name : undefined,
@@ -82,14 +91,28 @@ function readPackageMeta(dir) {
         return undefined;
     }
 }
+/** Read a package.json (if present) into the surface's package metadata. */
+function readPackageMeta(dir) {
+    const pkgPath = join(dir, 'package.json');
+    if (!existsSync(pkgPath))
+        return undefined;
+    try {
+        return packageMetaFromJson(readFileSync(pkgPath, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Build a scan surface from a local package directory: its implementation source
  * (for MTC-SRC-* analysis), its package metadata (for supply-chain checks), and
  * a tools manifest if the directory ships one (tools.json / mcp-tools.json).
  */
+/** Sidecar manifest file names a package may ship, in priority order. */
+export const SIDECAR_MANIFESTS = ['tools.json', 'mcp-tools.json', 'mcp.json'];
 export function surfaceFromPackageDir(dir) {
     let manifest = {};
-    for (const name of ['tools.json', 'mcp-tools.json', 'mcp.json']) {
+    for (const name of SIDECAR_MANIFESTS) {
         const p = join(dir, name);
         if (existsSync(p)) {
             try {

package/dist/cli/index.js

@@ -54,7 +54,8 @@ ${c.bold('Targets')}
   --scope <scope>                  OAuth scope to request with --login (e.g. mcp:tools)
   --header "Authorization: Bearer …"   static auth header instead of --login (repeatable)
   claude_desktop_config.json       a client config (scans each server)
-  @scope/package                   supply-chain / typosquat check (add --online for metadata)
+  @scope/package                   package scan (--online fetches metadata + reads the published source)
+  path/to/server.tgz|.whl|.zip     a packed release artifact — reads the shipped source (offline)
   --command "npx -y my-server"     spawn a local stdio server (sandboxed)
   --env KEY=VALUE                  env var for --command (repeatable)
 
@@ -75,7 +76,8 @@ ${c.bold('Options')}
   --no-lock                        skip the integrity (rug-pull) check
   --pin                            re-pin the lockfile after scanning
   --include-builtins               assume client built-in tools in toxic-flow analysis
-  --online                         allow network lookups for package metadata
+  --online                         allow network lookups: registry metadata + the verified published source
+  --metadata-only                  with --online: skip downloading the package artifact
   --run                            allow spawning servers found in a client config
   --allow-any-command              permit stdio commands outside the allowlist (dangerous)
   --allowed-hosts <a,b>            restrict live HTTP acquisition to these hosts
@@ -113,6 +115,7 @@ async function main() {
                 scope: { type: 'string' },
                 url: { type: 'string' },
                 online: { type: 'boolean' },
+                'metadata-only': { type: 'boolean' },
                 run: { type: 'boolean' },
                 'allow-any-command': { type: 'boolean' },
                 'allowed-hosts': { type: 'string' },
@@ -183,6 +186,7 @@ async function main() {
         args: buildArgs(values.command, values.args),
         url: values.url,
         online: values.online,
+        metadataOnly: values['metadata-only'],
         run: values.run,
         envVars: parseEnvFlags(values.env),
         allowAnyCommand: values['allow-any-command'],

package/dist/data/ruleCatalog.js

@@ -68,6 +68,7 @@ export const RULE_CATALOG = [
     { id: 'MTC-SUP-012', title: 'No license', category: 'hygiene', severity: 'low', summary: 'Package declares no license.' },
     { id: 'MTC-SUP-013', title: 'Package not version-pinned', category: 'supply-chain', severity: 'low', summary: 'Installed with @latest/floating spec — the rug-pull enabler; pinning is the recommended control.' },
     { id: 'MTC-SUP-014', title: 'Dependency squat / advisory match', category: 'supply-chain', severity: 'medium', summary: 'A declared dependency resembles a protected package or matches a known advisory by name.' },
+    { id: 'MTC-SUP-015', title: 'Pinned version is not published in the registry', category: 'supply-chain', severity: 'medium', summary: 'An exact pinned version is not listed by the registry; the scanner refuses to substitute latest and flags the gap.' },
     // Stage 6 — Posture / CVE
     { id: 'MTC-NET-001', title: 'Known-vulnerable version', category: 'supply-chain', severity: 'high', summary: 'Installed version is in a known-CVE range.' },
     { id: 'MTC-NET-002', title: 'User-controlled stdio command', category: 'network', severity: 'critical', summary: 'stdio command from untrusted config without an allowlist — stdio RCE class.' },
@@ -77,6 +78,9 @@ export const RULE_CATALOG = [
     { id: 'MTC-NET-006', title: 'Local HTTP/SSE — verify Origin (DNS rebinding)', category: 'network', severity: 'low', summary: 'A browser-reachable local MCP server is exposed to DNS rebinding unless it validates Host/Origin.' },
     // Stage 7 — Integrity
     { id: 'MTC-TOFU-001', title: 'Surface drift since pin (rug pull)', category: 'supply-chain', severity: 'high', summary: 'Canonical fingerprint no longer matches the pinned value.' },
+    { id: 'MTC-TOFU-002', title: 'Package republished with different content at the same version', category: 'supply-chain', severity: 'critical', summary: 'The verified artifact hash for the pinned version changed — same version, different published bytes (byte-level rug pull).' },
+    { id: 'MTC-TOFU-003', title: 'Published artifact failed integrity verification', category: 'supply-chain', severity: 'critical', summary: 'The downloaded artifact did not match the registry-declared hash, or was redirected off the registry host — tamper evidence; the bytes were not trusted.' },
+    { id: 'MTC-TOFU-004', title: 'Published-source byte check did not run', category: 'supply-chain', severity: 'info', summary: 'An online scan could not download the artifact; results reflect registry metadata only and are not source-verified.' },
     // Meta
     { id: 'MTC-META-001', title: 'Empty surface — nothing to analyze', category: 'hygiene', severity: 'info', summary: 'No tools/prompts/resources found; an empty surface is not a clean bill of health.' },
     // Stage 4b — Implementation-level source analysis (what the code DOES, not what the tool claims)

package/dist/detectors/source.js

@@ -23,9 +23,18 @@ export const sourceDetector = {
     stage: 4,
     title: 'Implementation-level source analysis',
     run(ctx) {
-        const files = Array.isArray(ctx.surface.sourceFiles) ? ctx.surface.sourceFiles : [];
-        if (!files.length)
+        const raw = Array.isArray(ctx.surface.sourceFiles) ? ctx.surface.sourceFiles : [];
+        if (!raw.length)
             return [];
+        // Process in a stable path order (code-unit, never locale) so the per-rule
+        // finding cap keeps the SAME findings regardless of how the caller ordered
+        // the files — the "same input ⇒ byte-identical report" promise must not
+        // depend on filesystem or archive iteration order.
+        const files = [...raw].sort((a, b) => {
+            const x = typeof a?.path === 'string' ? a.path : '';
+            const y = typeof b?.path === 'string' ? b.path : '';
+            return x < y ? -1 : x > y ? 1 : 0;
+        });
         const findings = [];
         const perRule = new Map();
         for (const f of files) {

package/dist/detectors/supplyChain.d.ts

@@ -14,4 +14,6 @@ export declare function analyzeTyposquat(name: string, meta: PackageMeta | undef
 export declare function analyzeProvenance(meta: PackageMeta): Finding[];
 /** Check a package's declared dependencies for squats / known-vuln names. */
 export declare function analyzeDependencies(meta: PackageMeta, config: ResolvedConfig): Finding[];
+/** Turn a failed published-artifact read into an honest finding (never silent). */
+export declare function analyzeArtifactError(meta: PackageMeta): Finding[];
 export declare const supplyChainDetector: Detector;