mcptrustchecker 1.1.0 → 1.3.0

package/README.md

@@ -9,10 +9,11 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Node](https://img.shields.io/badge/node-%E2%89%A520-3c873a.svg)](package.json)
 [![Methodology](https://img.shields.io/badge/methodology-mcptrustchecker--1.0-6f42c1.svg)](docs/methodology.md)
-[![Tests](https://img.shields.io/badge/tests-211%20passing-brightgreen.svg)](test)
-[![Rules](https://img.shields.io/badge/rules-74-orange.svg)](docs/rules.md)
+[![Tests](https://img.shields.io/badge/tests-304%20passing-brightgreen.svg)](test)
+[![Rules](https://img.shields.io/badge/rules-78-orange.svg)](docs/rules.md)
 [![No account](https://img.shields.io/badge/account-not%20required-brightgreen.svg)](#why-this-is-different)
 [![Offline](https://img.shields.io/badge/runs-100%25%20offline-brightgreen.svg)](#why-this-is-different)
+[![Free hosted API](https://img.shields.io/badge/hosted%20API-free-c4f542.svg)](https://mcptrustchecker.com/api)
 
 <br/>
 
@@ -24,7 +25,9 @@
 npx mcptrustchecker                # 🔍 scan every MCP server you already have installed — zero config
 ```
 
-<sub>· offline · deterministic · no account · OAuth browser login for protected servers · <a href="#the-algorithm-the-capability-flow-trust-model">one novel core</a> ·</sub>
+**Zero install?** Run the same deterministic engine as a **free public web API → [mcptrustchecker.com/api](https://mcptrustchecker.com/api)**
+
+<sub>· offline · deterministic · no account · OAuth browser login for protected servers · reads the real published npm/PyPI source · <a href="#the-algorithm-the-capability-flow-trust-model">one novel core</a> ·</sub>
 
 </div>
 
@@ -74,7 +77,9 @@ MCP Trust Checker's wedge is **accuracy + explainability + privacy**, with one g
 - 🔐 **Scans protected remote servers** — `--login` runs the full **OAuth 2.0 browser sign-in** (discovery → dynamic client registration → PKCE → token), so it can audit auth-gated remote MCP endpoints, not just public ones — something most scanners can't do. (Or pass a static `--header "Authorization: Bearer …"`.) Tokens stay in memory for the scan only.
 - 🎯 **Deterministic** — same input ⇒ byte-identical score, on every run and every machine.
 - 🕸️ **Cross-tool toxic-flow graph** — proves the lethal trifecta statically, composed across tools, not just within one.
-- 🔬 **Reads the code, not just the claim** — when the server's source is available (`scan ./path`), it grades what the implementation *does* (eval / shell-spawn / hardcoded egress / credential reads / obfuscated payloads), so a poisoned server can't hide behind honest-looking tool descriptions. Metadata **and** implementation, in one deterministic pass.
+- 🔬 **Reads the code, not just the claim** — it grades what the implementation *does* (eval / shell-spawn / hardcoded egress / credential reads / obfuscated payloads), so a poisoned server can't hide behind honest-looking tool descriptions. Metadata **and** implementation, in one deterministic pass.
+- 📥 **Deep-scans the actual published package** — `scan <name> --online` fetches the npm/PyPI artifact, verifies it against the registry-declared hash, and runs the full source-analysis engine on the exact bytes `npx`/`pip` would install — **in memory, without installing or executing anything**. Also scans packed release artifacts directly: `scan ./server.tgz`, `.whl`, `.zip`.
+- 🧬 **Byte-level rug-pull detection** — the verified artifact's SHA-256 is pinned in the lockfile; if the *same version* is ever republished with different bytes, the rescan raises a `critical`, `confirmed` finding (`MTC-TOFU-002`) — the attack an unchanged tool surface hides from every metadata-only check.
 - 🔎 **Decodes, not strips** — hidden Unicode payloads (Tags block / variation-selector) are recovered and shown as evidence.
 - 📌 **Rug-pull integrity** — the full tool surface is hashed and pinned; any post-approval drift trips a `confirmed` finding with a per-tool diff.
 - 🧾 **Auditable Trust Score** — every point is a published, reproducible penalty vector.
@@ -128,7 +133,9 @@ mcptrustchecker scan --command "npx -y @some/mcp-server"   # a local stdio serve
 mcptrustchecker scan https://mcp.example.com/mcp           # a live HTTP/SSE endpoint
 mcptrustchecker scan https://mcp.example.com/mcp --login   # an OAuth-protected endpoint (browser sign-in)
 mcptrustchecker scan https://mcp.example.com/mcp --header "Authorization: Bearer <token>"   # static auth
-mcptrustchecker scan @modelcontextprotocol/server-filesystem --online   # a package name (typosquat/CVE)
+mcptrustchecker scan @modelcontextprotocol/server-filesystem --online   # fetches + verifies + reads the PUBLISHED source
+mcptrustchecker scan mcp-server-fetch --online --registry pypi          # same for PyPI (sdist/wheel)
+mcptrustchecker scan ./server-1.2.0.tgz                    # a packed release artifact (.tgz/.whl/.zip) — offline
 ```
 
 **Outputs & CI gates:**
@@ -144,6 +151,8 @@ mcptrustchecker scan ./tools.json --min-grade B             # exit 1 below a gra
 
 The terminal report is **detailed by default** — every finding prints its full description (**what** the problem is and **why** it matters), the exact location, the offending **evidence**, a **fix**, and its OWASP mapping, grouped most-severe-first. Add `--details` for external references, or `--quiet` for just the grade line.
 
+**No install? Use the free hosted API.** A hosted version of the exact same deterministic engine runs at **[mcptrustchecker.com/api](https://mcptrustchecker.com/api)** — POST a `tools.json` manifest or a published npm/PyPI package name over a single HTTPS request and get the same auditable A–F Trust Score back as JSON. It is **completely free** (grab a key in seconds, no card, no account), and it's the quickest way to try the scanner without installing anything. The CLI and library stay 100% offline — the hosted API is an optional convenience.
+
 ---
 
 ## The algorithm: the Capability-Flow Trust Model
@@ -238,20 +247,22 @@ Full list: **[docs/rules.md](docs/rules.md)** · run `mcptrustchecker rules`.
 
 ---
 
-## Two axes: Trust (grade) and Capability (blast radius)
+## Three axes: Trust (grade), Capability (blast radius), Coverage (depth)
 
-A single number can't answer "should I use this server?" — because **"powerful" and "malicious" are different questions.** A web scraper legitimately needs to fetch untrusted pages and act on them; that's a large *blast radius*, not evidence it's a bad actor. So MCP Trust Checker reports two independent things:
+A single number can't answer "should I use this server?" — because **"powerful" and "malicious" are different questions**, and a clean grade means nothing if the scan barely saw the server. So MCP Trust Checker reports three independent things:
 
 - **Trust — the A–F grade.** Driven by *threat* signals: prompt-injection with concealment, embedded secrets, Unicode smuggling, typosquatting, known CVEs, rug-pull drift, annotation lies, a single tool built as an exfiltration primitive. Answers **"any sign this server is malicious or negligent?"**
 - **Capability — a level (Minimal → Critical).** Driven by what the server *can do*: code execution, filesystem writes, network egress, the cross-tool toxic-flow surface. Answers **"how much damage if the model driving it is manipulated?"** — a fact to size access against, **not** a mark against the server.
+- **Coverage — a level (Live → Source → Manifest → Metadata → Empty).** How much the scan could actually inspect. A Grade A from a `metadata`-only scan (no tools enumerated, no code read) is **not** the assurance of a Grade A from a `live` scan that saw the real runtime tools. Coverage never changes the score — it states the score's reach, so a shallow scan is never mistaken for a clean bill of health. When coverage is partial, the report says exactly what it could not see.
 
 ```
-firecrawl   Trust B (81/100)   Capability CRITICAL   → trustworthy, but huge blast radius — grant carefully
-poisoned    Trust F            Capability HIGH        → actual malice signals — avoid
-memory      Trust A (100)      Capability MINIMAL     → safe and low-power
+firecrawl   Trust B (81/100)   Capability CRITICAL   Coverage LIVE     → trustworthy, but huge blast radius — grant carefully
+poisoned    Trust F            Capability HIGH        Coverage LIVE     → actual malice signals — avoid
+memory      Trust A (100)      Capability MINIMAL     Coverage LIVE     → safe and low-power
+some-pkg    Trust A (98)       Capability MINIMAL     Coverage METADATA → clean *so far* — 0 tools seen; scan the live server
 ```
 
-This is why MCP Trust Checker doesn't collapse every capable server into "F" (which would make the grade useless). Popularity is never an input — popular packages get compromised — but a legitimate powerful server keeps a high Trust grade while its Capability is surfaced honestly.
+This is why MCP Trust Checker doesn't collapse every capable server into "F" (which would make the grade useless). Popularity is never an input — popular packages get compromised — but a legitimate powerful server keeps a high Trust grade while its Capability and the scan's Coverage are surfaced honestly.
 
 ## The Trust grade is auditable by construction
 
@@ -364,7 +375,7 @@ Connecting to an MCP config can run arbitrary commands. MCP Trust Checker's acqu
 
 - **[docs/methodology.md](docs/methodology.md)** — every pipeline stage in depth
 - **[docs/scoring.md](docs/scoring.md)** — the scoring model & reproducibility contract
-- **[docs/rules.md](docs/rules.md)** — the complete 74-rule catalogue
+- **[docs/rules.md](docs/rules.md)** — the complete 78-rule catalogue
 - **[docs/architecture.md](docs/architecture.md)** — code layout & how to extend
 - **[docs/ci-integration.md](docs/ci-integration.md)** — Action, SARIF, baselines
 - **[SECURITY.md](SECURITY.md)** · **[CONTRIBUTING.md](CONTRIBUTING.md)**

package/dist/acquire/archive.d.ts

@@ -0,0 +1,55 @@
+/*! MCP Trust Checker · https://mcptrustchecker.com · support@mcptrustchecker.com · © 2026 Illia Haidar · MIT */
+/**
+ * Dependency-free, in-memory archive readers (ustar/pax tar, gzip, zip) so the
+ * scanner can read the *published bytes* of a package — npm tarballs, PyPI
+ * sdists and wheels, packed release artifacts — without ever writing them to
+ * disk or executing anything. Every reader is bounded (entry count, per-file
+ * size, total size, decompressed size) so a hostile archive (zip bomb, header
+ * spoofing, path traversal) can degrade a scan, not the machine running it.
+ */
+export interface ArchiveEntry {
+    /** Normalized relative path inside the archive (always `/`-separated). */
+    path: string;
+    data: Buffer;
+}
+export interface ArchiveLimits {
+    maxFiles: number;
+    maxFileBytes: number;
+    maxTotalBytes: number;
+}
+/** Decompressed-archive safety cap: a .tgz may not inflate past this. */
+export declare const MAX_UNPACKED_BYTES: number;
+/**
+ * Normalize an archive member path and reject anything that could mislead a
+ * report or (defense-in-depth) escape a directory: `..` segments, drive
+ * letters, NUL bytes. Absolute paths are made relative — entries are only ever
+ * held in memory, the path just labels evidence.
+ */
+export declare function safeEntryPath(raw: string): string | null;
+/** Gunzip with a hard output cap so a gzip bomb can't exhaust memory. */
+export declare function gunzipBounded(buf: Buffer, maxBytes?: number): Buffer;
+/**
+ * Read regular files out of a (already-decompressed) ustar/pax tar buffer.
+ * Handles POSIX prefix fields, pax `path` overrides and GNU longnames; skips
+ * directories, links and device nodes; stops on the first malformed header
+ * rather than guessing at offsets.
+ */
+export declare function extractTar(tar: Buffer, wanted: (path: string) => boolean, limits: ArchiveLimits): ArchiveEntry[];
+/**
+ * Read regular files out of a zip buffer (PyPI wheels, .zip sdists, .mcpb-style
+ * bundles) via the central directory. Supports stored and deflate entries;
+ * skips encrypted entries and directories; zip64 archives are rejected (a
+ * package artifact has no business being >4 GB).
+ */
+export declare function extractZip(zip: Buffer, wanted: (path: string) => boolean, limits: ArchiveLimits): ArchiveEntry[];
+export type ArchiveKind = 'tar' | 'tgz' | 'zip';
+/** Sniff the archive container by magic bytes, falling back to the file name. */
+export declare function detectArchiveKind(buf: Buffer, nameHint?: string): ArchiveKind;
+/** One entry point: sniff the container, decompress if needed, extract. */
+export declare function extractArchive(buf: Buffer, nameHint: string, wanted: (path: string) => boolean, limits: ArchiveLimits): ArchiveEntry[];
+/**
+ * Strip the single shared top-level directory when every entry lives under one
+ * (npm's `package/`, a PyPI sdist's `name-version/`) so paths read like the
+ * package root. Archives with multiple roots (wheels) are left untouched.
+ */
+export declare function stripCommonRoot(entries: ArchiveEntry[]): ArchiveEntry[];

package/dist/acquire/archive.js

@@ -0,0 +1,318 @@
+/*! MCP Trust Checker · https://mcptrustchecker.com · support@mcptrustchecker.com · © 2026 Illia Haidar · MIT */
+/**
+ * Dependency-free, in-memory archive readers (ustar/pax tar, gzip, zip) so the
+ * scanner can read the *published bytes* of a package — npm tarballs, PyPI
+ * sdists and wheels, packed release artifacts — without ever writing them to
+ * disk or executing anything. Every reader is bounded (entry count, per-file
+ * size, total size, decompressed size) so a hostile archive (zip bomb, header
+ * spoofing, path traversal) can degrade a scan, not the machine running it.
+ */
+import { gunzipSync, inflateRawSync } from 'node:zlib';
+/** Decompressed-archive safety cap: a .tgz may not inflate past this. */
+export const MAX_UNPACKED_BYTES = 200 * 1024 * 1024; // 200 MB
+const TAR_BLOCK = 512;
+/**
+ * Normalize an archive member path and reject anything that could mislead a
+ * report or (defense-in-depth) escape a directory: `..` segments, drive
+ * letters, NUL bytes. Absolute paths are made relative — entries are only ever
+ * held in memory, the path just labels evidence.
+ */
+export function safeEntryPath(raw) {
+    const norm = raw.replace(/\\/g, '/');
+    if (!norm || norm.includes('\0'))
+        return null;
+    const parts = norm.split('/').filter((p) => p !== '' && p !== '.');
+    if (parts.length === 0)
+        return null;
+    if (parts.some((p) => p === '..'))
+        return null;
+    if (/^[a-zA-Z]:$/.test(parts[0]))
+        return null;
+    return parts.join('/');
+}
+/** Gunzip with a hard output cap so a gzip bomb can't exhaust memory. */
+export function gunzipBounded(buf, maxBytes = MAX_UNPACKED_BYTES) {
+    try {
+        return gunzipSync(buf, { maxOutputLength: maxBytes });
+    }
+    catch (err) {
+        throw new Error(`Failed to decompress gzip data (corrupt, or larger than the ${Math.round(maxBytes / 1024 / 1024)} MB safety cap): ${err.message}`);
+    }
+}
+/** Octal (or GNU base-256) numeric field from a tar header. NaN on garbage. */
+function tarNumber(header, off, len) {
+    if (header[off] & 0x80) {
+        // GNU base-256 for values that don't fit in octal.
+        let v = header[off] & 0x7f;
+        for (let i = 1; i < len; i++)
+            v = v * 256 + header[off + i];
+        return v;
+    }
+    const s = header.toString('ascii', off, off + len).replace(/\0[\s\S]*$/, '').trim();
+    if (!s)
+        return 0;
+    const v = parseInt(s, 8);
+    return Number.isFinite(v) ? v : NaN;
+}
+function tarString(header, off, len) {
+    return header.toString('utf8', off, off + len).replace(/\0[\s\S]*$/, '');
+}
+/**
+ * Only these pax keys can override an entry's path — the rest are irrelevant to
+ * source extraction, so we never build a map of attacker-chosen keys (a hostile
+ * header can otherwise carry millions of distinct keys; see MAX_PAX_RECORDS).
+ */
+const PAX_WANTED_KEYS = new Set(['path', 'linkpath']);
+/** Hard cap on records parsed from one pax header (defense-in-depth vs. key-flooding). */
+const MAX_PAX_RECORDS = 4096;
+/** Parse the pax keys we care about from a header body: `"<len> <key>=<value>\n"`. */
+function parsePax(body) {
+    const out = {};
+    let off = 0;
+    let records = 0;
+    while (off < body.length && records < MAX_PAX_RECORDS) {
+        const sp = body.indexOf(0x20, off);
+        if (sp < 0)
+            break;
+        const len = parseInt(body.toString('ascii', off, sp), 10);
+        if (!Number.isFinite(len) || len <= 0 || off + len > body.length)
+            break;
+        records++;
+        const eq = body.indexOf(0x3d, sp + 1); // '='
+        if (eq > 0 && eq < off + len) {
+            const key = body.toString('utf8', sp + 1, eq);
+            // Only materialize values for keys that can affect extraction.
+            if (PAX_WANTED_KEYS.has(key))
+                out[key] = body.toString('utf8', eq + 1, off + len).replace(/\n$/, '');
+        }
+        off += len;
+    }
+    return out;
+}
+/**
+ * Read regular files out of a (already-decompressed) ustar/pax tar buffer.
+ * Handles POSIX prefix fields, pax `path` overrides and GNU longnames; skips
+ * directories, links and device nodes; stops on the first malformed header
+ * rather than guessing at offsets.
+ */
+export function extractTar(tar, wanted, limits) {
+    const out = [];
+    let total = 0;
+    let off = 0;
+    let gnuLongName;
+    let paxPath;
+    while (off + TAR_BLOCK <= tar.length) {
+        const header = tar.subarray(off, off + TAR_BLOCK);
+        if (header.every((b) => b === 0))
+            break; // end-of-archive marker
+        const size = tarNumber(header, 124, 12);
+        if (!Number.isFinite(size) || size < 0 || off + TAR_BLOCK + size > tar.length)
+            break;
+        const dataStart = off + TAR_BLOCK;
+        const next = dataStart + Math.ceil(size / TAR_BLOCK) * TAR_BLOCK;
+        const type = String.fromCharCode(header[156]);
+        // A metadata block (GNU longname / pax header) precedes a real entry and is
+        // discarded after one use. Its `size` is bounded only by the archive length,
+        // so a hostile ~190 MB longname/pax body would be materialized OUTSIDE the
+        // per-file cap — cap it here (a legitimate path/header is far under 512 KB).
+        if (type === 'L' || type === 'K') {
+            // GNU longname/longlink: the data block holds the NEXT entry's path.
+            if (size <= limits.maxFileBytes && type === 'L') {
+                gnuLongName = tar.subarray(dataStart, dataStart + size).toString('utf8').replace(/\0[\s\S]*$/, '');
+            }
+            off = next;
+            continue;
+        }
+        if (type === 'x' || type === 'g') {
+            // pax extended header ('g' is global — applied conservatively to the next entry only).
+            if (size <= limits.maxFileBytes) {
+                const pax = parsePax(tar.subarray(dataStart, dataStart + size));
+                if (type === 'x' && pax.path)
+                    paxPath = pax.path;
+            }
+            off = next;
+            continue;
+        }
+        let name = tarString(header, 0, 100);
+        const prefix = tarString(header, 345, 155);
+        if (prefix)
+            name = `${prefix}/${name}`;
+        if (gnuLongName)
+            name = gnuLongName;
+        if (paxPath)
+            name = paxPath; // pax path wins over both
+        gnuLongName = undefined;
+        paxPath = undefined;
+        // '0' and NUL are regular files; everything else (dirs, links, devices) is skipped.
+        if (type === '0' || type === '\0') {
+            const path = safeEntryPath(name);
+            if (path && size <= limits.maxFileBytes && wanted(path)) {
+                if (out.length >= limits.maxFiles || total + size > limits.maxTotalBytes)
+                    return out;
+                out.push({ path, data: Buffer.from(tar.subarray(dataStart, dataStart + size)) });
+                total += size;
+            }
+        }
+        off = next;
+    }
+    return out;
+}
+const ZIP_EOCD_SIG = 0x06054b50;
+const ZIP_CDIR_SIG = 0x02014b50;
+const ZIP_LOCAL_SIG = 0x04034b50;
+function findEocd(zip) {
+    const floor = Math.max(0, zip.length - 22 - 65535);
+    for (let i = zip.length - 22; i >= floor; i--) {
+        if (zip.readUInt32LE(i) === ZIP_EOCD_SIG)
+            return i;
+    }
+    return -1;
+}
+/**
+ * Read regular files out of a zip buffer (PyPI wheels, .zip sdists, .mcpb-style
+ * bundles) via the central directory. Supports stored and deflate entries;
+ * skips encrypted entries and directories; zip64 archives are rejected (a
+ * package artifact has no business being >4 GB).
+ */
+export function extractZip(zip, wanted, limits) {
+    const eocd = findEocd(zip);
+    if (eocd < 0)
+        throw new Error('Not a zip archive (no end-of-central-directory record).');
+    const count = zip.readUInt16LE(eocd + 10);
+    const cdOffset = zip.readUInt32LE(eocd + 16);
+    if (count === 0xffff || cdOffset === 0xffffffff)
+        throw new Error('zip64 archives are not supported.');
+    const out = [];
+    // Three independent budgets bound a hostile zip's work:
+    //  • `total`         — decompression OUTPUT (charged even for a discarded
+    //                      over-cap inflate), so an output-bomb can't bypass it;
+    //  • `inflatedBytes` — compressed INPUT actually fed to zlib, so a stream that
+    //                      inflates to ~0 output (empty stored blocks) but reads a
+    //                      huge compressed region still hits a ceiling — the input
+    //                      work amplified by many CD entries pointing at one blob;
+    //  • `seen` offsets  — a physical stream is inflated AT MOST ONCE, so N central-
+    //                      directory entries aliasing one local header do N× nothing.
+    // `processed` additionally bounds the entry count. Any single guard tripping
+    // stops extraction, so worst-case CPU is bounded regardless of archive shape.
+    let total = 0;
+    let inflatedBytes = 0;
+    let processed = 0;
+    const seen = new Set();
+    let p = cdOffset;
+    for (let i = 0; i < count && p + 46 <= zip.length; i++) {
+        if (zip.readUInt32LE(p) !== ZIP_CDIR_SIG)
+            break;
+        const flags = zip.readUInt16LE(p + 8);
+        const method = zip.readUInt16LE(p + 10);
+        const compSize = zip.readUInt32LE(p + 20);
+        const uncompSize = zip.readUInt32LE(p + 24);
+        const nameLen = zip.readUInt16LE(p + 28);
+        const extraLen = zip.readUInt16LE(p + 30);
+        const commentLen = zip.readUInt16LE(p + 32);
+        const localOff = zip.readUInt32LE(p + 42);
+        const rawName = zip.toString('utf8', p + 46, p + 46 + nameLen);
+        p += 46 + nameLen + extraLen + commentLen;
+        if (flags & 0x0041)
+            continue; // encrypted (bit 0) / strong encryption (bit 6)
+        if (rawName.endsWith('/'))
+            continue; // directory
+        const path = safeEntryPath(rawName);
+        // Cheap rejections (bad path, declared over-cap, unwanted, over-budget
+        // compressed size, or an already-inflated stream) cost no decompression.
+        if (!path || uncompSize > limits.maxFileBytes || !wanted(path))
+            continue;
+        if (compSize > limits.maxTotalBytes || seen.has(localOff))
+            continue;
+        // Stop before any more work once ANY budget is spent.
+        if (processed >= limits.maxFiles || total >= limits.maxTotalBytes || inflatedBytes >= limits.maxTotalBytes)
+            break;
+        // Local header re-read: its name/extra lengths can differ from the central directory's.
+        if (localOff + 30 > zip.length || zip.readUInt32LE(localOff) !== ZIP_LOCAL_SIG)
+            continue;
+        const lNameLen = zip.readUInt16LE(localOff + 26);
+        const lExtraLen = zip.readUInt16LE(localOff + 28);
+        const dataOff = localOff + 30 + lNameLen + lExtraLen;
+        if (dataOff + compSize > zip.length)
+            continue;
+        const comp = zip.subarray(dataOff, dataOff + compSize);
+        // Bound each inflate by the smaller of the per-file cap and the remaining
+        // output budget; charge both the output produced and the input consumed.
+        seen.add(localOff);
+        processed++;
+        inflatedBytes += compSize;
+        const budget = Math.min(limits.maxFileBytes, limits.maxTotalBytes - total);
+        let data;
+        if (method === 0) {
+            if (compSize !== uncompSize || uncompSize > budget) {
+                total += Math.min(compSize, budget);
+                continue;
+            }
+            data = Buffer.from(comp);
+        }
+        else if (method === 8) {
+            try {
+                data = inflateRawSync(comp, { maxOutputLength: budget });
+            }
+            catch {
+                total += budget; // over-cap or corrupt: charge the bounded work we just did
+                continue;
+            }
+        }
+        else {
+            continue; // unsupported compression method — no work done
+        }
+        if (data.length > limits.maxFileBytes) {
+            total += data.length;
+            continue;
+        }
+        out.push({ path, data });
+        total += data.length;
+    }
+    return out;
+}
+/** Sniff the archive container by magic bytes, falling back to the file name. */
+export function detectArchiveKind(buf, nameHint = '') {
+    if (buf.length >= 2 && buf[0] === 0x1f && buf[1] === 0x8b)
+        return 'tgz';
+    if (buf.length >= 4 && buf.readUInt32LE(0) === ZIP_LOCAL_SIG)
+        return 'zip';
+    if (buf.length >= 22 && findEocd(buf) >= 0)
+        return 'zip';
+    if (buf.length >= 265 && buf.toString('ascii', 257, 262) === 'ustar')
+        return 'tar';
+    const lower = nameHint.toLowerCase();
+    if (lower.endsWith('.zip') || lower.endsWith('.whl'))
+        return 'zip';
+    if (lower.endsWith('.tar'))
+        return 'tar';
+    return 'tgz';
+}
+/** One entry point: sniff the container, decompress if needed, extract. */
+export function extractArchive(buf, nameHint, wanted, limits) {
+    const kind = detectArchiveKind(buf, nameHint);
+    if (kind === 'zip')
+        return extractZip(buf, wanted, limits);
+    const tar = kind === 'tgz' ? gunzipBounded(buf) : buf;
+    return extractTar(tar, wanted, limits);
+}
+/**
+ * Strip the single shared top-level directory when every entry lives under one
+ * (npm's `package/`, a PyPI sdist's `name-version/`) so paths read like the
+ * package root. Archives with multiple roots (wheels) are left untouched.
+ */
+export function stripCommonRoot(entries) {
+    if (entries.length === 0)
+        return entries;
+    let root;
+    for (const e of entries) {
+        const slash = e.path.indexOf('/');
+        if (slash <= 0)
+            return entries; // a top-level file — nothing to strip
+        const first = e.path.slice(0, slash);
+        if (root === undefined)
+            root = first;
+        else if (root !== first)
+            return entries; // multiple roots — leave as-is
+    }
+    return entries.map((e) => ({ path: e.path.slice(root.length + 1), data: e.data }));
+}

package/dist/acquire/index.d.ts

@@ -15,6 +15,8 @@ export interface ResolveOptions extends LiveOptions {
     registry?: 'npm' | 'pypi';
     /** Environment variables to pass to a `--command` stdio server. */
     envVars?: Record<string, string>;
+    /** With `--online`: skip downloading the published artifact (metadata checks only). */
+    metadataOnly?: boolean;
 }
 export interface ResolvedTarget {
     label: string;

package/dist/acquire/index.js

@@ -10,16 +10,37 @@ import { surfaceFromPackageDir } from './source.js';
 import { acquireHttp, acquireStdio, ALLOWED_COMMANDS } from './live.js';
 import { expandVars, isClientConfig, packageSpecFromStdio, parseClientConfig, redactSensitiveArgs, } from './clientConfig.js';
 import { fetchNpmMeta, fetchPypiMeta } from './npm.js';
+import { fetchPackageSource, surfaceFromArchiveFile, PackageSourceError } from './packageSource.js';
 const NPM_NAME = /^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/i;
 const HTTP_RE = /^https?:\/\//i;
+/** Split a `name` / `name@version` / `@scope/name@version` target. */
+function parsePackageTarget(target) {
+    const scoped = target.startsWith('@');
+    const at = target.indexOf('@', scoped ? 1 : 0);
+    if (at <= 0)
+        return { name: target };
+    return { name: target.slice(0, at), version: target.slice(at + 1) || undefined };
+}
 function commandBase(command) {
     const cleaned = command.replace(/\\/g, '/');
     return cleaned.slice(cleaned.lastIndexOf('/') + 1);
 }
-async function metaFor(name, opts) {
+/** Map a stdio runner command to the registry that runner installs from. */
+function registryForRunner(command) {
+    if (!command)
+        return undefined;
+    const base = command.replace(/\\/g, '/');
+    const runner = base.slice(base.lastIndexOf('/') + 1).replace(/\.(cmd|exe)$/, '');
+    if (runner === 'uvx' || runner === 'pipx' || runner === 'pip' || runner === 'pip3' || runner.startsWith('python'))
+        return 'pypi';
+    if (runner === 'npx' || runner === 'bunx' || runner === 'pnpm' || runner === 'yarn' || runner === 'node')
+        return 'npm';
+    return undefined;
+}
+async function metaFor(name, opts, registry, version) {
     if (!opts.online)
-        return { registry: opts.registry ?? 'npm', name };
-    return opts.registry === 'pypi' ? fetchPypiMeta(name) : fetchNpmMeta(name);
+        return { registry, name };
+    return registry === 'pypi' ? fetchPypiMeta(name, version) : fetchNpmMeta(name, version);
 }
 function packageSurface(name, meta, origin) {
     return {
@@ -32,6 +53,38 @@ function packageSurface(name, meta, origin) {
         packageMeta: meta,
     };
 }
+/**
+ * Fetch + verify the package's published artifact and attach its real source to
+ * the surface (the deep half of an `--online` package scan).
+ *
+ * Failure handling is fail-CLOSED for tampering and fail-OPEN for outages, but
+ * NEVER silent: a hash mismatch or an off-allowlist redirect (hard tamper
+ * evidence) is recorded on the surface so a detector raises a finding — it must
+ * not degrade to a clean grade. A transient network failure is recorded too, so
+ * a machine consumer can see the byte-level check did not run rather than
+ * mistaking an unverified scan for a verified one.
+ */
+async function attachPublishedSource(surface, opts) {
+    const meta = surface.packageMeta;
+    if (!opts.online || opts.metadataOnly || !meta?.tarballUrl)
+        return;
+    try {
+        const src = await fetchPackageSource(meta);
+        if (!src)
+            return;
+        meta.tarballSha256 = src.tarballSha256;
+        surface.sourceFiles = src.sourceFiles;
+    }
+    catch (err) {
+        const kind = err instanceof PackageSourceError ? err.kind : 'other';
+        const detail = err.message;
+        meta.artifactError = { kind, detail };
+        const label = kind === 'integrity' || kind === 'untrusted-redirect'
+            ? 'artifact FAILED verification'
+            : 'artifact byte-check skipped';
+        process.stderr.write(`! ${surface.id}: ${label} (${detail}).\n`);
+    }
+}
 /** Strip the query string from a stored URL so config-embedded tokens don't leak. */
 function redactUrl(url) {
     if (!url)
@@ -85,9 +138,14 @@ export async function resolveTargets(target, opts = {}) {
     }
     if (!target)
         throw new Error('No scan target provided.');
-    // A scoped npm/PyPI package (@scope/name) contains '/' but is NOT a path.
-    const isScopedPkg = /^@[a-z0-9-~][a-z0-9-._~]*\/[a-z0-9-~][a-z0-9-._~]*$/i.test(target);
-    const looksLikePath = !isScopedPkg && (target.includes('/') || target.includes('\\') || target.toLowerCase().endsWith('.json'));
+    // A scoped npm/PyPI package (@scope/name, optionally @version) contains '/'
+    // but is NOT a path — e.g. `@modelcontextprotocol/server-filesystem@1.0.0`.
+    // A scoped-SHAPED string ending in an archive/.json extension is a FILE path
+    // (e.g. `@myorg/server-1.0.0.tgz`), so it must not shadow the not-found guard.
+    const isArchiveFile = /\.(tgz|tar\.gz|tar|zip|whl)$/i.test(target);
+    const hasFileExt = isArchiveFile || target.toLowerCase().endsWith('.json');
+    const isScopedPkg = !hasFileExt && /^@[a-z0-9-~][a-z0-9-._~]*\/[a-z0-9-~][a-z0-9-._~]*(@[^/\\]+)?$/i.test(target);
+    const looksLikePath = !isScopedPkg && (target.includes('/') || target.includes('\\') || target.toLowerCase().endsWith('.json') || isArchiveFile);
     // A path/manifest target that doesn't exist: say so plainly.
     if (looksLikePath && !existsSync(target)) {
         throw new Error(`No such file: ${target}`);
@@ -96,6 +154,11 @@ export async function resolveTargets(target, opts = {}) {
     if (existsSync(target) && statSync(target).isDirectory()) {
         return [{ label: target, surface: surfaceFromPackageDir(target) }];
     }
+    // A packed release artifact (.tgz/.tar.gz/.tar/.zip/.whl) → read the real
+    // shipped source in memory, offline, without installing or executing it.
+    if (isArchiveFile && existsSync(target) && statSync(target).isFile()) {
+        return [{ label: target, surface: surfaceFromArchiveFile(target) }];
+    }
     // 2) A file on disk: manifest or client config.
     if (existsSync(target) && target.toLowerCase().endsWith('.json')) {
         let json;
@@ -146,10 +209,17 @@ export async function resolveTargets(target, opts = {}) {
                     const pkgSpec = packageSpecFromStdio(spec.command, spec.args ?? []);
                     // Only fetch metadata for a well-formed package name (config values are untrusted).
                     if (pkgSpec && NPM_NAME.test(pkgSpec.name)) {
-                        const meta = await metaFor(pkgSpec.name, opts);
+                        // Pick the registry from the RUNNER (uvx/pipx → PyPI, npx → npm), not
+                        // the global --registry default, so a Python server isn't looked up
+                        // (and its same-named npm squat isn't downloaded) as an npm package.
+                        const registry = registryForRunner(spec.command) ?? opts.registry ?? 'npm';
+                        const meta = await metaFor(pkgSpec.name, opts, registry, pkgSpec.version);
                         meta.requestedSpec = pkgSpec.version;
                         meta.pinned = Boolean(pkgSpec.version && pkgSpec.version !== 'latest' && /^[0-9]/.test(pkgSpec.version));
                         surface.packageMeta = meta;
+                        // The config names the package the runner would install — read its
+                        // actual published source (the pinned version), not just its metadata.
+                        await attachPublishedSource(surface, opts);
                     }
                 }
                 results.push({ label: spec.id, surface });
@@ -165,10 +235,18 @@ export async function resolveTargets(target, opts = {}) {
         const surface = surfaceFromManifest(json, target);
         return [{ label: surface.id, surface }];
     }
-    // 3) A bare package name → supply-chain / provenance scan.
-    if (NPM_NAME.test(target)) {
-        const meta = await metaFor(target, opts);
-        return [{ label: target, surface: packageSurface(target, meta, target) }];
+    // 3) A bare package name (optionally `name@version`) → supply-chain /
+    // provenance scan; with `--online` the published artifact of the requested
+    // version is fetched, verified and read as real source.
+    const bare = parsePackageTarget(target);
+    if (bare && NPM_NAME.test(bare.name)) {
+        const registry = opts.registry ?? 'npm';
+        const meta = await metaFor(bare.name, opts, registry, bare.version);
+        meta.requestedSpec = bare.version;
+        meta.pinned = Boolean(bare.version && /^\d/.test(bare.version));
+        const surface = packageSurface(bare.name, meta, target);
+        await attachPublishedSource(surface, opts);
+        return [{ label: target, surface }];
     }
     throw new Error(`Could not resolve target "${target}". Provide a tools.json manifest, an http(s) URL, ` +
         `a client config, a package name, or use --command for stdio.`);

package/dist/acquire/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>;