@4da/mcp-server 5.0.3 → 6.0.0

package/dist/live/lockfile-types.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The shape every lockfile reader returns, shared by lockfile-parsers.ts,
+ * lockfile-parsers-pygo.ts and js-lockfile-readers.ts.
+ */
+/** One installed copy of a package. `dev` is undefined when the lockfile does not say. */
+export interface PackageInstance {
+    name: string;
+    version: string;
+    dev?: boolean;
+}
+/** Versions read from one directory, and the file they came from. */
+export interface VersionSource {
+    /** The version a direct dependency of this name resolves to. */
+    versions: Map<string, string>;
+    /** Every installed copy, deduplicated by name@version. */
+    instances: PackageInstance[];
+    /** Absolute path of the file the versions were read from, or null when none exists. */
+    source: string | null;
+    /** `lockfile` = exact versions; `manifest` = read from a manifest (pins or specifier floors). */
+    kind: "lockfile" | "manifest" | null;
+}
+export declare function emptySource(): VersionSource;
+/**
+ * Collects instances deduplicated by name@version. A copy seen as runtime
+ * anywhere stays runtime; dev is only claimed when every sighting says dev,
+ * and unknown when any sighting does not say.
+ */
+export declare class InstanceSet {
+    private byKey;
+    add(name: string, version: string, dev?: boolean): void;
+    get size(): number;
+    toArray(): PackageInstance[];
+}
+export declare function found(versions: Map<string, string>, instances: InstanceSet | PackageInstance[], source: string, kind: "lockfile" | "manifest"): VersionSource;

package/dist/live/lockfile-types.js

@@ -0,0 +1,42 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * The shape every lockfile reader returns, shared by lockfile-parsers.ts,
+ * lockfile-parsers-pygo.ts and js-lockfile-readers.ts.
+ */
+export function emptySource() {
+    return { versions: new Map(), instances: [], source: null, kind: null };
+}
+/**
+ * Collects instances deduplicated by name@version. A copy seen as runtime
+ * anywhere stays runtime; dev is only claimed when every sighting says dev,
+ * and unknown when any sighting does not say.
+ */
+export class InstanceSet {
+    byKey = new Map();
+    add(name, version, dev) {
+        const key = `${name}\0${version}`;
+        const existing = this.byKey.get(key);
+        if (!existing) {
+            this.byKey.set(key, dev === undefined ? { name, version } : { name, version, dev });
+            return;
+        }
+        if (existing.dev === undefined || dev === undefined)
+            delete existing.dev;
+        else
+            existing.dev = existing.dev && dev;
+    }
+    get size() {
+        return this.byKey.size;
+    }
+    toArray() {
+        return [...this.byKey.values()];
+    }
+}
+export function found(versions, instances, source, kind) {
+    return {
+        versions,
+        instances: Array.isArray(instances) ? instances : instances.toArray(),
+        source,
+        kind,
+    };
+}

package/dist/live/maintenance.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Maintenance-notice predicate, shared by every consumer of a vulnerability
+ * scan (vulnerability_scan, get_actionable_signals, what_should_i_know,
+ * dependency_health) so they all draw the same line.
+ */
+import type { VulnerabilityEntry } from "./types.js";
+/**
+ * Is this advisory a maintenance notice rather than a vulnerability?
+ *
+ * RustSec publishes "X is unmaintained" as an advisory so tooling can see it,
+ * and OSV carries it through with no severity and no fixed version. It is real
+ * information — an unmaintained dependency is a risk to plan around — but it is
+ * not something an attacker can exploit and not something you can upgrade away
+ * today, so it does not belong in the same list, the same count, or the same
+ * "Review X" recommendation as a live CVE.
+ *
+ * Live scan: 23 of 41 findings were these (the whole gtk-rs GTK3 family, all
+ * five `unic-*` crates, `paste`, `proc-macro-error`, `ttf-parser`), producing
+ * 27 "Review" lines around six genuinely actionable upgrades.
+ *
+ * Matched on the advisory's own wording, which RustSec keeps consistent, and
+ * deliberately NOT on "deprecated" — that word appears in plenty of real
+ * vulnerability summaries.
+ */
+export declare function isMaintenanceNotice(v: Pick<VulnerabilityEntry, "summary">): boolean;
+/**
+ * The advisories a scan can actually ask the user to act on today: built on
+ * this host AND exploitable (not a maintenance notice). This is the set
+ * `vulnerability_scan` reports as `vulnerabilities` / `total_vulnerable_packages`;
+ * every other tool that counts "vulnerable" must count the same set or the
+ * numbers disagree across tools over one scan.
+ */
+export declare function isActionableVulnerability(v: Pick<VulnerabilityEntry, "summary" | "platformActive">): boolean;

package/dist/live/maintenance.js

@@ -0,0 +1,37 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Maintenance-notice predicate, shared by every consumer of a vulnerability
+ * scan (vulnerability_scan, get_actionable_signals, what_should_i_know,
+ * dependency_health) so they all draw the same line.
+ */
+/**
+ * Is this advisory a maintenance notice rather than a vulnerability?
+ *
+ * RustSec publishes "X is unmaintained" as an advisory so tooling can see it,
+ * and OSV carries it through with no severity and no fixed version. It is real
+ * information — an unmaintained dependency is a risk to plan around — but it is
+ * not something an attacker can exploit and not something you can upgrade away
+ * today, so it does not belong in the same list, the same count, or the same
+ * "Review X" recommendation as a live CVE.
+ *
+ * Live scan: 23 of 41 findings were these (the whole gtk-rs GTK3 family, all
+ * five `unic-*` crates, `paste`, `proc-macro-error`, `ttf-parser`), producing
+ * 27 "Review" lines around six genuinely actionable upgrades.
+ *
+ * Matched on the advisory's own wording, which RustSec keeps consistent, and
+ * deliberately NOT on "deprecated" — that word appears in plenty of real
+ * vulnerability summaries.
+ */
+export function isMaintenanceNotice(v) {
+    return /\b(unmaintained|no longer maintained)\b/i.test(v.summary || "");
+}
+/**
+ * The advisories a scan can actually ask the user to act on today: built on
+ * this host AND exploitable (not a maintenance notice). This is the set
+ * `vulnerability_scan` reports as `vulnerabilities` / `total_vulnerable_packages`;
+ * every other tool that counts "vulnerable" must count the same set or the
+ * numbers disagree across tools over one scan.
+ */
+export function isActionableVulnerability(v) {
+    return v.platformActive !== false && !isMaintenanceNotice(v);
+}

package/dist/live/npm-packument.d.ts

@@ -0,0 +1,47 @@
+/**
+ * npm full-packument reader for dependency_check.
+ *
+ * The abbreviated metadata the freshness reader uses carries no publish times,
+ * publishers, attestations, scripts or per-version dependencies, so this reads
+ * the FULL packument (`GET registry.npmjs.org/<name>`) and keeps only what the
+ * signals need. Some packuments are ~15 MB, so the projection is cached on
+ * disk (the live_cache table) together with the registry's ETag, and later
+ * reads revalidate with `If-None-Match` — an unchanged package costs a 304.
+ *
+ * Privacy: the request names the package and nothing else. The installed
+ * version is never sent; versions are picked out of the full list locally.
+ */
+import type { LiveCache } from "./cache.js";
+import type { RateLimiter } from "./rate-limiter.js";
+import type { PackageReleaseIndex, RegistryLookup, ReleaseMetadataSource } from "./release-metadata.js";
+interface NpmVersionDoc {
+    _npmUser?: {
+        name?: string;
+        trustedPublisher?: {
+            id?: string;
+        } | null;
+    };
+    dist?: {
+        attestations?: unknown;
+    };
+    scripts?: Record<string, string>;
+    gypfile?: boolean;
+    hasInstallScript?: boolean;
+    dependencies?: Record<string, string>;
+    optionalDependencies?: Record<string, string>;
+    deprecated?: string;
+}
+export interface NpmPackument {
+    versions?: Record<string, NpmVersionDoc>;
+    time?: Record<string, unknown>;
+}
+export declare class NpmPackumentReader implements ReleaseMetadataSource {
+    private cache;
+    private rateLimiter;
+    constructor(cache: LiveCache, rateLimiter: RateLimiter);
+    getReleases(name: string): Promise<RegistryLookup<PackageReleaseIndex>>;
+    getCreatedAt(name: string): Promise<RegistryLookup<string | null>>;
+}
+/** Keep only what dependency_check reads. Exported for tests. */
+export declare function projectPackument(name: string, doc: NpmPackument): PackageReleaseIndex;
+export {};

package/dist/live/npm-packument.js

@@ -0,0 +1,150 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * npm full-packument reader for dependency_check.
+ *
+ * The abbreviated metadata the freshness reader uses carries no publish times,
+ * publishers, attestations, scripts or per-version dependencies, so this reads
+ * the FULL packument (`GET registry.npmjs.org/<name>`) and keeps only what the
+ * signals need. Some packuments are ~15 MB, so the projection is cached on
+ * disk (the live_cache table) together with the registry's ETag, and later
+ * reads revalidate with `If-None-Match` — an unchanged package costs a 304.
+ *
+ * Privacy: the request names the package and nothing else. The installed
+ * version is never sent; versions are picked out of the full list locally.
+ */
+import { fetchWithTimeout } from "./http-utils.js";
+const NPM_REGISTRY_URL = "https://registry.npmjs.org";
+// Full packuments can be large; 8 s (the abbreviated reader's budget) is not enough.
+const PACKUMENT_TIMEOUT_MS = 30_000;
+/** Serve the cached projection without revalidating for this long. */
+const FRESH_MS = 15 * 60 * 1000;
+/** Keep the row (and its ETag) this long so revalidation survives restarts. */
+const ROW_TTL_SECONDS = 7 * 86_400;
+const INSTALL_HOOKS = ["preinstall", "install", "postinstall"];
+export class NpmPackumentReader {
+    cache;
+    rateLimiter;
+    constructor(cache, rateLimiter) {
+        this.cache = cache;
+        this.rateLimiter = rateLimiter;
+    }
+    async getReleases(name) {
+        const key = `npm-packument:${name}`;
+        const cached = this.cache.getStale(key)?.data ?? null;
+        if (cached && Date.now() - cached.fetchedAtMs < FRESH_MS) {
+            return { status: "ok", data: cached.index };
+        }
+        if (!this.rateLimiter.consume("npm")) {
+            return { status: "unreachable", detail: "npm registry rate limit reached for this minute" };
+        }
+        const headers = { Accept: "application/json" };
+        if (cached?.etag)
+            headers["If-None-Match"] = cached.etag;
+        let response;
+        try {
+            response = await fetchWithTimeout(`${NPM_REGISTRY_URL}/${encodeURIComponent(name)}`, { headers }, PACKUMENT_TIMEOUT_MS);
+        }
+        catch (err) {
+            return { status: "unreachable", detail: `npm registry: ${errorText(err)}` };
+        }
+        if (response.status === 304 && cached) {
+            this.cache.set(key, { ...cached, fetchedAtMs: Date.now() }, "npm", ROW_TTL_SECONDS);
+            return { status: "ok", data: cached.index };
+        }
+        if (response.status === 404) {
+            return { status: "not_found", detail: `"${name}" is not on the public npm registry` };
+        }
+        if (!response.ok) {
+            return { status: "unreachable", detail: `npm registry answered HTTP ${response.status}` };
+        }
+        let doc;
+        try {
+            doc = (await response.json());
+        }
+        catch (err) {
+            return { status: "unreachable", detail: `npm registry: unreadable packument (${errorText(err)})` };
+        }
+        const index = projectPackument(name, doc);
+        this.cache.set(key, { etag: response.headers.get("etag"), fetchedAtMs: Date.now(), index }, "npm", ROW_TTL_SECONDS);
+        return { status: "ok", data: index };
+    }
+    async getCreatedAt(name) {
+        const lookup = await this.getReleases(name);
+        return lookup.status === "ok" ? { status: "ok", data: lookup.data.createdAt } : lookup;
+    }
+}
+/** Keep only what dependency_check reads. Exported for tests. */
+export function projectPackument(name, doc) {
+    const time = doc.time ?? {};
+    const releases = {};
+    for (const [version, v] of Object.entries(doc.versions ?? {})) {
+        const { trust, trustEvidence } = npmTrust(v);
+        releases[version] = {
+            version,
+            publishedAt: typeof time[version] === "string" ? time[version] : null,
+            trust,
+            trustEvidence,
+            installScripts: installScriptsOf(v),
+            deprecated: typeof v.deprecated === "string" && v.deprecated.length > 0 ? v.deprecated : null,
+            withdrawn: null,
+            dependencies: [
+                ...new Set([...Object.keys(v.dependencies ?? {}), ...Object.keys(v.optionalDependencies ?? {})]),
+            ],
+        };
+    }
+    // A version listed in `time` but absent from `versions` was unpublished —
+    // npm keeps the timestamp so the number can never be reused. The 2026-03-31
+    // axios 1.14.1 / 0.30.4 releases look exactly like this today.
+    const unpublished = new Set();
+    for (const k of Object.keys(time)) {
+        if (k !== "created" && k !== "modified" && k !== "unpublished" && !releases[k])
+            unpublished.add(k);
+    }
+    const whole = time.unpublished;
+    if (whole && Array.isArray(whole.versions)) {
+        for (const v of whole.versions)
+            if (typeof v === "string" && !releases[v])
+                unpublished.add(v);
+    }
+    for (const version of unpublished) {
+        releases[version] = {
+            version,
+            publishedAt: typeof time[version] === "string" ? time[version] : null,
+            trust: 0,
+            trustEvidence: "unknown (release unpublished; its metadata is gone)",
+            installScripts: null,
+            deprecated: null,
+            withdrawn: "unpublished",
+            dependencies: null,
+        };
+    }
+    return {
+        ecosystem: "npm",
+        name,
+        createdAt: typeof time.created === "string" ? time.created : null,
+        releases,
+    };
+}
+function npmTrust(v) {
+    const tp = v._npmUser?.trustedPublisher;
+    if (tp)
+        return { trust: 2, trustEvidence: `trusted publisher (${tp.id ?? "OIDC"})` };
+    if (v.dist?.attestations)
+        return { trust: 1, trustEvidence: "provenance attestation, no trusted publisher" };
+    const who = v._npmUser?.name ? ` (published by npm user "${v._npmUser.name}")` : "";
+    return { trust: 0, trustEvidence: `no trusted publisher or provenance attestation${who}` };
+}
+function installScriptsOf(v) {
+    const found = INSTALL_HOOKS.filter((hook) => typeof v.scripts?.[hook] === "string");
+    // npm runs `node-gyp rebuild` as an implicit install script when the package
+    // ships a binding.gyp and declares no install/preinstall of its own.
+    if (v.gypfile && !found.includes("install") && !found.includes("preinstall")) {
+        found.push("install (implicit node-gyp rebuild)");
+    }
+    if (found.length === 0 && v.hasInstallScript)
+        found.push("install script (hasInstallScript)");
+    return found;
+}
+function errorText(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/live/npm-registry.js

@@ -22,57 +22,33 @@ export class NpmRegistry {
         this.rateLimiter = rateLimiter;
     }
     async getPackageInfo(name, currentVersion, isDev) {
-        const cacheKey = `npm-reg:${name}`;
-        const cached = this.cache.get(cacheKey);
-        if (cached !== null)
-            return cached;
-        if (!this.rateLimiter.canProceed("npm")) {
-            const stale = this.cache.getStale(cacheKey);
-            if (stale)
-                return stale.data;
-            return errorResult(name, currentVersion, isDev, "Rate limited");
-        }
-        try {
-            this.rateLimiter.consume("npm");
-            const meta = await fetchJson(`${NPM_REGISTRY_URL}/${encodeURIComponent(name)}`, { headers: { Accept: "application/vnd.npm.install-v1+json" } }, NPM_TIMEOUT_MS);
-            const latestTag = meta["dist-tags"]?.latest ?? null;
-            const versions = Object.keys(meta.versions || {});
-            // Latest stable = last version that is not a prerelease
-            const latestStable = findLatestStable(versions);
-            // Check deprecation on the latest version entry
-            const latestVersionEntry = latestTag ? meta.versions[latestTag] : null;
-            const deprecated = !!latestVersionEntry?.deprecated;
-            const deprecationMessage = latestVersionEntry?.deprecated ?? null;
-            // Semver distance between current and latest stable (or latest tag)
-            let versionsBehind = null;
-            if (currentVersion && (latestStable || latestTag)) {
-                versionsBehind = computeSemverDistance(currentVersion, latestStable || latestTag);
+        // The cache holds facts about the PACKAGE; the answer is computed for the
+        // installed version on every call. It used to cache the finished answer by
+        // name, so the second project to ask about a package got the first one's
+        // `currentVersion` and distance.
+        const cacheKey = `npm-facts:${name}`;
+        let facts = this.cache.get(cacheKey);
+        if (facts === null) {
+            if (!this.rateLimiter.canProceed("npm")) {
+                facts = this.cache.getStale(cacheKey)?.data ?? null;
+                if (!facts)
+                    return errorResult(name, currentVersion, isDev, "Rate limited");
+            }
+            else {
+                try {
+                    this.rateLimiter.consume("npm");
+                    const meta = await fetchJson(`${NPM_REGISTRY_URL}/${encodeURIComponent(name)}`, { headers: { Accept: "application/vnd.npm.install-v1+json" } }, NPM_TIMEOUT_MS);
+                    facts = packageFacts(meta);
+                    this.cache.set(cacheKey, facts, "npm", NPM_CACHE_TTL);
+                }
+                catch (err) {
+                    facts = this.cache.getStale(cacheKey)?.data ?? null;
+                    if (!facts)
+                        return errorResult(name, currentVersion, isDev, err instanceof Error ? err.message : String(err));
+                }
             }
-            const result = {
-                name,
-                ecosystem: "npm",
-                currentVersion,
-                latestVersion: latestTag,
-                latestStableVersion: latestStable,
-                versionsBehind,
-                deprecated,
-                deprecationMessage,
-                lastPublished: meta.modified ?? null,
-                license: null, // abbreviated metadata does not include license
-                weeklyDownloads: null, // fetched separately via getBulkDownloads
-                isDev,
-                fetchError: null,
-            };
-            this.cache.set(cacheKey, result, "npm", NPM_CACHE_TTL);
-            return result;
-        }
-        catch (err) {
-            const stale = this.cache.getStale(cacheKey);
-            if (stale)
-                return stale.data;
-            const message = err instanceof Error ? err.message : String(err);
-            return errorResult(name, currentVersion, isDev, message);
         }
+        return infoFor(name, currentVersion, isDev, facts);
     }
     async getBulkDownloads(names) {
         const result = new Map();
@@ -127,10 +103,48 @@ export class NpmRegistry {
         return result;
     }
 }
-// Semver-max, not last-published: maintenance releases of older lines are
-// published after newer lines (see maxStableSemver).
-function findLatestStable(versions) {
-    return maxStableSemver(versions);
+function packageFacts(meta) {
+    const deprecations = {};
+    for (const [version, entry] of Object.entries(meta.versions || {})) {
+        if (entry?.deprecated)
+            deprecations[version] = entry.deprecated;
+    }
+    return {
+        latestTag: meta["dist-tags"]?.latest ?? null,
+        // Semver-max, not last-published: maintenance releases of older lines are
+        // published after newer lines (see maxStableSemver).
+        latestStable: maxStableSemver(Object.keys(meta.versions || {})),
+        modified: meta.modified ?? null,
+        deprecations,
+    };
+}
+/**
+ * The answer for one installed version. Deprecation is the INSTALLED
+ * version's first (that is what the project runs): `mkdirp@0.5.1` is
+ * deprecated on npm while its latest is not, and checking only the latest
+ * entry reported it healthy. A deprecated latest still marks the whole
+ * package deprecated.
+ */
+function infoFor(name, currentVersion, isDev, facts) {
+    const installedDeprecation = currentVersion ? facts.deprecations[currentVersion] : undefined;
+    const latestDeprecation = facts.latestTag ? facts.deprecations[facts.latestTag] : undefined;
+    const target = facts.latestStable || facts.latestTag;
+    const versionsBehind = currentVersion && target ? computeSemverDistance(currentVersion, target) : null;
+    return {
+        name,
+        ecosystem: "npm",
+        currentVersion,
+        latestVersion: facts.latestTag,
+        latestStableVersion: facts.latestStable,
+        versionsBehind,
+        deprecated: Boolean(installedDeprecation || latestDeprecation),
+        deprecationMessage: installedDeprecation ?? latestDeprecation ?? null,
+        lastPublished: facts.modified,
+        license: null, // abbreviated metadata does not include license
+        weeklyDownloads: null, // fetched separately via getBulkDownloads
+        isDev,
+        fetchError: null,
+    };
 }
 function errorResult(name, currentVersion, isDev, fetchError) {
     return {

package/dist/live/osv-scanner.d.ts

@@ -8,7 +8,7 @@
  */
 import type { LiveCache } from "./cache.js";
 import type { RateLimiter } from "./rate-limiter.js";
-import type { ResolvedDependency, VulnerabilityScanResult } from "./types.js";
+import type { ResolvedDependency, OsvVulnerability, VulnerabilityEntry, VulnerabilityScanResult } from "./types.js";
 export declare class OsvScanner {
     private cache;
     private rateLimiter;
@@ -24,7 +24,37 @@ export declare class OsvScanner {
     private hydrateDetails;
     private fetchDetail;
 }
+/**
+ * Overwrite the dep-context fields of a cached advisory entry with the CURRENT
+ * resolution's context. The advisory facts (id, severity, summary, fix version)
+ * are stable and cacheable; `platformActive`, `target`, `sourceDirs`, and the
+ * dev/direct flags are functions of TODAY's dependency resolution, not of the
+ * advisory. Serving them from cache bakes yesterday's context into today's
+ * scan — observed live 2026-08-30: a pre-platform-filter scan cached `glib`
+ * as platform-active and `sandbox` with no source dirs, and every scan for the
+ * next hour repeated both errors while the fixed resolver sat idle.
+ */
+export declare function restampDepContext(cached: VulnerabilityEntry, dep: ResolvedDependency): VulnerabilityEntry;
 export declare function extractCvssScore(severity: Array<{
     type: string;
     score: string;
 }> | undefined): number | null;
+/**
+ * Pick the fix version for the OSV range that actually CONTAINS the installed
+ * version — never another release line's fix. The old code returned the first
+ * range's first `fixed` event, so a multi-range advisory (e.g. undici fixed at
+ * 6.x on the 6 line and 7.x on the 7 line) recommended a DOWNGRADE to 6.x for
+ * an installed 7.x.
+ *
+ * Selection order:
+ * 1. The `fixed` of the interval containing installed (introduced <= installed
+ *    < fixed).
+ * 2. If that interval has no fix (or none contains installed), the smallest
+ *    published fix strictly ABOVE installed across all ranges.
+ * 3. If the installed version is unparseable, the highest published fix (it
+ *    resolves the advisory regardless of release line).
+ * 4. Otherwise null — omitting the recommendation beats emitting a downgrade.
+ *
+ * Hard guard: the returned version is never below the installed version.
+ */
+export declare function extractFixedVersion(affected: OsvVulnerability["affected"] | undefined, packageName: string, ecosystem: string, installedVersion: string | null): string | null;