mcptrustchecker 1.0.0 → 1.2.0

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

@@ -30,6 +30,7 @@ import { GRADE_RANK } from '../scoring/model.js';
 import { RULE_CATALOG, findRule } from '../data/ruleCatalog.js';
 import { METHODOLOGY_VERSION, TOOL_VERSION } from '../version.js';
 import { c } from '../util/ansi.js';
+import { parseHeaderArgs } from '../util/headers.js';
 const KNOWN_COMMANDS = new Set(['scan', 'pin', 'diff', 'rules', 'explain', 'version', 'help']);
 function fail(msg, code = 2) {
     process.stderr.write(`${c.red('mcptrustchecker: error')} ${msg}\n`);
@@ -49,8 +50,12 @@ ${c.bold('Usage')}
 ${c.bold('Targets')}
   path/to/tools.json               a pre-generated manifest (offline)
   https://host/mcp                 a live Streamable-HTTP / SSE endpoint
+  --login                          OAuth browser sign-in for a protected endpoint (opens your browser)
+  --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)
 
@@ -71,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
@@ -104,8 +110,12 @@ async function main() {
                 command: { type: 'string' },
                 args: { type: 'string' },
                 env: { type: 'string', multiple: true },
+                header: { type: 'string', multiple: true },
+                login: { type: 'boolean' },
+                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' },
@@ -176,12 +186,23 @@ 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'],
         allowedHosts: values['allowed-hosts'] ? values['allowed-hosts'].split(',').map((h) => h.trim()) : undefined,
+        headers: parseHeaderArgs(values.header),
+        login: values.login,
+        scope: values.scope,
         registry: values.registry === 'pypi' ? 'pypi' : 'npm',
     };
+    // --login and a static Authorization header are alternative auth methods;
+    // combining them would silently clobber the freshly-minted OAuth token.
+    if (values.login &&
+        resolveOpts.headers &&
+        Object.keys(resolveOpts.headers).some((h) => h.toLowerCase() === 'authorization')) {
+        fail('--login cannot be combined with a static --header "Authorization: …" — choose one auth method.');
+    }
     let resolved = [];
     if (autoDiscover) {
         // Zero-config: find and scan every installed MCP client config.

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;

package/dist/detectors/supplyChain.js

@@ -224,6 +224,67 @@ export function analyzeDependencies(meta, config) {
     }
     return findings;
 }
+/** Turn a failed published-artifact read into an honest finding (never silent). */
+export function analyzeArtifactError(meta) {
+    if (meta.requestedVersionMissing) {
+        return [
+            {
+                ruleId: 'MTC-SUP-015',
+                title: 'Pinned version is not published in the registry',
+                category: 'supply-chain',
+                severity: 'medium',
+                confidence: 'strong',
+                description: `The exact version you pinned (${meta.version ?? meta.requestedSpec ?? 'requested'}) is not listed by the ` +
+                    `registry — it may have been unpublished or yanked, or a hostile registry response may be hiding it to serve ` +
+                    `a different "latest". The scanner did NOT silently substitute another version: no source was read and no ` +
+                    `byte pin was recorded for a version that isn't there.`,
+                remediation: 'Confirm the version still exists and is the one you intend to install; if it was yanked, pin a known-good ' +
+                    'version and re-pin. Treat an unexpectedly-missing pinned version as a supply-chain signal.',
+                location: { kind: 'package', name: meta.name },
+                owasp: 'LLM03:2025 Supply Chain',
+                evidence: `requested ${meta.requestedSpec ?? meta.version ?? ''}`.trim(),
+            },
+        ];
+    }
+    const err = meta.artifactError;
+    if (!err)
+        return [];
+    if (err.kind === 'integrity' || err.kind === 'untrusted-redirect') {
+        return [
+            {
+                ruleId: 'MTC-TOFU-003',
+                title: 'Published artifact failed integrity verification',
+                category: 'supply-chain',
+                severity: 'critical',
+                confidence: 'confirmed',
+                description: `The published artifact for this package could not be verified against the registry's own declared hash ` +
+                    `(or was served from a host outside the registry's allowlist). Its bytes were NOT trusted, scanned, or ` +
+                    `pinned. This is exactly the signal a CDN/MITM tamper or a spoofed registry response would produce.\n  • ${err.detail}`,
+                remediation: 'Do not install this package until resolved: re-fetch from a trusted network, confirm the registry ' +
+                    'metadata, and compare the artifact hash against a known-good source.',
+                location: { kind: 'package', name: meta.name },
+                owasp: 'LLM03:2025 Supply Chain',
+                evidence: err.detail,
+            },
+        ];
+    }
+    // Transient/other: not an attack claim, but the scan is NOT verified — say so.
+    return [
+        {
+            ruleId: 'MTC-TOFU-004',
+            title: 'Published-source byte check did not run',
+            category: 'supply-chain',
+            severity: 'info',
+            confidence: 'heuristic',
+            description: `An online scan was requested but the published artifact could not be downloaded, so the implementation ` +
+                `source was NOT read and the byte-level integrity pin was NOT recorded. This scan reflects registry ` +
+                `metadata only — treat it as incomplete, not as a clean bill of health.\n  • ${err.detail}`,
+            remediation: 'Re-run the scan when the registry/network is reachable to complete the source-level analysis.',
+            location: { kind: 'package', name: meta.name },
+            evidence: err.detail,
+        },
+    ];
+}
 export const supplyChainDetector = {
     id: 'supply-chain',
     stage: 5,
@@ -237,6 +298,7 @@ export const supplyChainDetector = {
         if (meta) {
             findings.push(...analyzeProvenance(meta));
             findings.push(...analyzeDependencies(meta, ctx.config));
+            findings.push(...analyzeArtifactError(meta));
         }
         return findings;
     },

package/dist/engine.js

@@ -62,22 +62,46 @@ export async function scanSurface(rawSurface, options = {}) {
     if (options.lockfile !== undefined) {
         integrity = checkIntegrity(surface, options.lockfile);
         if (integrity.status === 'drift') {
-            raw.push({
-                ruleId: 'MTC-TOFU-001',
-                title: 'Server surface changed since it was pinned (possible rug pull)',
-                category: 'supply-chain',
-                severity: 'high',
-                confidence: 'confirmed',
-                description: `The canonical fingerprint of this server no longer matches its pinned value in the lockfile. ` +
-                    `Tool definitions can change silently after you approve them (a rug pull); review every change before ` +
-                    `trusting it again.\n` +
-                    (integrity.changes ?? []).map((c) => `  • ${c.detail}`).join('\n'),
-                remediation: 'Review the diff; re-pin only after confirming the changes are legitimate (`mcptrustchecker pin`).',
-                location: { kind: 'server' },
-                owasp: 'LLM03:2025 Supply Chain',
-                evidence: `${integrity.changes?.length ?? 0} change(s) since pin`,
-                data: { changes: integrity.changes },
-            });
+            const allChanges = integrity.changes ?? [];
+            const packageChanges = allChanges.filter((ch) => ch.kind === 'package-changed');
+            const surfaceChanges = allChanges.filter((ch) => ch.kind !== 'package-changed');
+            if (surfaceChanges.length > 0 || integrity.currentDigest !== integrity.previousDigest) {
+                raw.push({
+                    ruleId: 'MTC-TOFU-001',
+                    title: 'Server surface changed since it was pinned (possible rug pull)',
+                    category: 'supply-chain',
+                    severity: 'high',
+                    confidence: 'confirmed',
+                    description: `The canonical fingerprint of this server no longer matches its pinned value in the lockfile. ` +
+                        `Tool definitions can change silently after you approve them (a rug pull); review every change before ` +
+                        `trusting it again.\n` +
+                        surfaceChanges.map((c) => `  • ${c.detail}`).join('\n'),
+                    remediation: 'Review the diff; re-pin only after confirming the changes are legitimate (`mcptrustchecker pin`).',
+                    location: { kind: 'server' },
+                    owasp: 'LLM03:2025 Supply Chain',
+                    evidence: `${surfaceChanges.length} change(s) since pin`,
+                    data: { changes: surfaceChanges },
+                });
+            }
+            if (packageChanges.length > 0) {
+                raw.push({
+                    ruleId: 'MTC-TOFU-002',
+                    title: 'Package republished with different content at the same version',
+                    category: 'supply-chain',
+                    severity: 'critical',
+                    confidence: 'confirmed',
+                    description: `The registry artifact for the pinned version no longer contains the bytes that were verified at pin ` +
+                        `time. The tool surface can look completely unchanged while the implementation behind it was swapped — ` +
+                        `the byte-level rug pull that metadata-only checks cannot see.\n` +
+                        packageChanges.map((c) => `  • ${c.detail}`).join('\n'),
+                    remediation: 'Treat this as a potential supply-chain compromise: diff the published code against the version you ' +
+                        'approved before trusting it again, and re-pin (`mcptrustchecker pin`) only after review.',
+                    location: { kind: 'package', name: packageChanges[0].name },
+                    owasp: 'LLM03:2025 Supply Chain',
+                    evidence: packageChanges[0].detail,
+                    data: { changes: packageChanges },
+                });
+            }
         }
     }
     // Filter: disabled rules, whole-rule allowlist waivers, and location-scoped

package/dist/lockfile.d.ts

@@ -12,6 +12,17 @@ export interface LockEntry {
     digest: string;
     tools: Record<string, string>;
     instructionsDigest: string;
+    /** Package version whose published artifact was verified at pin time. */
+    packageVersion?: string;
+    /**
+     * Identity of the pinned artifact (its registry URL). A registry can publish
+     * several artifacts per version (a PyPI sdist AND wheels); the byte pin is
+     * only comparable to the SAME artifact, so a later-added sibling artifact
+     * isn't mistaken for a same-version republish.
+     */
+    tarballUrl?: string;
+    /** SHA-256 of that verified artifact — pins the actual published bytes. */
+    tarballSha256?: string;
     pinnedAt?: string;
 }
 export interface Lockfile {