@superblocksteam/vite-plugin-file-sync 2.0.149 → 2.0.150-next.1

package/dist/ai-service/app-interface/shell.js

@@ -32,16 +32,19 @@ var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn,
     if (target) Object.defineProperty(target, contextIn.name, descriptor);
     done = true;
 };
-import { exec } from "node:child_process";
+import { exec, execFile } from "node:child_process";
 import { readFile as fsReadFile, mkdir, writeFile, access, rm, stat, readdir, } from "node:fs/promises";
 import * as path from "node:path";
 import { promisify } from "node:util";
+import { metrics } from "@opentelemetry/api";
 import { glob } from "glob";
 import JSON5 from "json5";
 import { detect, resolveCommand } from "package-manager-detector";
+import semver from "semver";
 import { normalizePath } from "vite";
 import { isProtectedCorePackage } from "@superblocksteam/library-shared/types";
 import { bucketNpmRegistryHost, recordNpmInstall, } from "@superblocksteam/telemetry";
+import { applyPackageJsonSubstitutions, readDeclaredDependencies, } from "../../npm/apply-package-json-substitutions.js";
 import { preparePackageJsonForCloudNpm } from "../../npm/prepare-package-json-for-cloud-npm.js";
 import { getErrorMeta, getLogger } from "../../util/logger.js";
 import llmobs from "../llmobs/index.js";
@@ -52,7 +55,9 @@ import { DraftManager, validateFileOperation, } from "./filesystem/index.js";
 import { Linter } from "./linter.js";
 import { parseNpmJsonDiagnostic, parseNpmJsonError, parseNpmJsonSuccess, } from "./npm-error-parser.js";
 import { prepareForPrivateRegistry, shouldIgnoreInstallScripts, } from "./npm-registry.js";
+import { applyPackageSubstitutions, runVulnerabilityGate, } from "./vulnerability-gate.js";
 const execPromise = promisify(exec);
+const execFilePromise = promisify(execFile);
 // `npm install --json` emits the full install summary on stdout. The default
 // 1 MiB exec buffer can be exceeded for fat dependency trees, which would
 // fail a successful install with ERR_CHILD_PROCESS_STDIO_MAXBUFFER and reach
@@ -61,6 +66,79 @@ const execPromise = promisify(exec);
 // covers real-world npm summaries (per-package entries are tiny) while
 // keeping the worst-case buffer + parsed-object peak bounded.
 const NPM_JSON_MAX_BUFFER = 4 * 1024 * 1024;
+/** Lowest version a declared range admits; skips `workspace:`/`file:`/`*`/git. */
+function declaredRangeFloor(range) {
+    if (range == null || semver.validRange(range) == null)
+        return null;
+    const floor = semver.minVersion(range);
+    if (floor == null)
+        return null;
+    // `*` floors to 0.0.0; an exact `0.0.0` pin is real.
+    if (floor.version === "0.0.0" && semver.valid(range) == null)
+        return null;
+    return floor.version;
+}
+function emitIndexUnavailableMetric() {
+    metrics
+        .getMeter("superblocks.clark.pkg_security")
+        .createCounter("superblocks.clark.pkg_security.index_unavailable", {
+        description: "Vulnerability index unavailable during Clark package-install gate",
+    })
+        .add(1);
+}
+/**
+ * npm `--json` stdout can be prefixed with non-JSON status lines on some
+ * versions (`add foo 1.2.3\n{...}`). Slice from the first `{`.
+ */
+function parseNpmJsonStdout(stdout) {
+    if (typeof stdout !== "string" || stdout.length === 0) {
+        throw new Error("npm --json stdout contained no JSON object");
+    }
+    const start = stdout.indexOf("{");
+    if (start < 0) {
+        throw new Error("npm --json stdout contained no JSON object");
+    }
+    return JSON.parse(stdout.slice(start));
+}
+/** True for npm `--json` failure bodies (`{ "error": ... }`), not dry-run trees. */
+function isNpmErrorEnvelope(parsed) {
+    if (parsed == null || typeof parsed !== "object")
+        return false;
+    if (!("error" in parsed))
+        return false;
+    return parsed.error != null;
+}
+/**
+ * True for an npm dry-run entry installed into the app's own `node_modules`
+ * (`<app>/node_modules/lodash`) rather than nested under a dependency
+ * (`<app>/node_modules/@scope/library/node_modules/lodash`). npm omits `path`
+ * on some shapes; treat those as top-level so a missing field cannot hide a
+ * package from the top-level CVE checks.
+ */
+function isRootNodeModulesPath(entryPath) {
+    if (typeof entryPath !== "string" || entryPath.length === 0)
+        return true;
+    return entryPath.replace(/\\/g, "/").split("/node_modules/").length <= 2;
+}
+function packageNameFromLockPath(lockPath) {
+    if (!lockPath)
+        return undefined;
+    const marker = "node_modules/";
+    const idx = lockPath.lastIndexOf(marker);
+    if (idx < 0)
+        return undefined;
+    const name = lockPath.slice(idx + marker.length);
+    return name.length > 0 ? name : undefined;
+}
+function isPackageLookupResult(value) {
+    if (value == null || typeof value !== "object")
+        return false;
+    const record = value;
+    return (typeof record.name === "string" &&
+        typeof record.version === "string" &&
+        typeof record.hasMalware === "boolean" &&
+        Array.isArray(record.advisories));
+}
 /**
  * Map an install failure to a value in the closed `npm.outcome` enum
  * (APPS-4189). `NpmInstallBlocked` carries the structured reason from
@@ -194,12 +272,18 @@ let AppShell = (() => {
          * The reporter is fire-and-forget — see `maybeReportBlockedInstall`.
          */
         reportNpmInstallBlocked;
+        /**
+         * Optional deps for the install-time vulnerability index lookup.
+         * When absent the malware/CVE gate is skipped (test fixtures / deliberate
+         * opt-out). Production AiService always wires these.
+         */
+        packageLookup;
         /**
          * Tracks files that must be read before they can be written.
          * Used to enforce read-before-write pattern for AI safety.
          */
         requiredReads = new Set();
-        constructor({ appRootDirPath, fsOperationQueue, messageSender, draftInterface, templateRenderer, virtualFileSystem, pathValidator, enableDeletingLockfiles, npmRegistryClient, reportNpmInstallBlocked, }) {
+        constructor({ appRootDirPath, fsOperationQueue, messageSender, draftInterface, templateRenderer, virtualFileSystem, pathValidator, enableDeletingLockfiles, npmRegistryClient, reportNpmInstallBlocked, packageLookup, }) {
             // Normalize path to handle Windows drive letter case
             this.appRootDirPath = normalizePath(appRootDirPath);
             this.fsOperationQueue = fsOperationQueue;
@@ -214,6 +298,7 @@ let AppShell = (() => {
             this.enableDeletingLockfiles = enableDeletingLockfiles ?? false;
             this.npmRegistryClient = npmRegistryClient;
             this.reportNpmInstallBlocked = reportNpmInstallBlocked;
+            this.packageLookup = packageLookup;
         }
         /**
          * Toggle the API virtual-file projection. When disabled, reads to `apis/*`
@@ -658,25 +743,118 @@ let AppShell = (() => {
          * server throttles + sanitizes + persists. Fire-and-forget: a reporting
          * failure must never surface to (or break) the install caller.
          */
+        safeAudit(report) {
+            if (!this.reportNpmInstallBlocked)
+                return;
+            try {
+                this.reportNpmInstallBlocked(report);
+            }
+            catch {
+                // Audit reporting is best-effort and must not affect the install.
+            }
+        }
         maybeReportBlockedInstall(err, runner) {
             if (!(err instanceof NpmInstallBlocked))
                 return;
-            if (!this.reportNpmInstallBlocked)
+            // Audit only real CVE/malware findings — index/probe failures are fail-closed
+            // blocks, not malware hits, and must not pollute SIEM as vulnerabilities.
+            const isAuditableFinding = (finding) => finding.kind === "cve" || finding.kind === "malware";
+            const vulnerabilities = err.findings?.filter(isAuditableFinding).map((finding) => ({
+                advisoryId: finding.advisoryId,
+                kind: finding.kind,
+                package: finding.package,
+                ...(finding.severity !== undefined
+                    ? { severity: finding.severity }
+                    : {}),
+                ...(finding.suggestedVersion !== undefined
+                    ? { suggestedVersion: finding.suggestedVersion }
+                    : {}),
+            }));
+            // A block whose findings are all index/probe outages still carries
+            // `reason: vulnerable_package`, so auditing it would file an outage as a
+            // CVE hit. The `index_unavailable` metric already covers those.
+            if (err.findings?.length && !vulnerabilities?.length)
                 return;
-            try {
-                this.reportNpmInstallBlocked({
-                    reason: err.reason,
-                    registryHost: err.registryHost,
-                    packages: err.packages,
-                    httpStatus: err.httpStatus,
-                    npmErrorCode: err.npmErrorCode,
+            this.safeAudit({
+                reason: err.reason,
+                registryHost: err.registryHost,
+                packages: err.packages,
+                httpStatus: err.httpStatus,
+                npmErrorCode: err.npmErrorCode,
+                runner,
+                occurredAt: Date.now(),
+                ...(vulnerabilities?.length ? { vulnerabilities } : {}),
+            });
+        }
+        reportNpmTriageVerdict(verdict) {
+            this.safeAudit({
+                occurredAt: Date.now(),
+                packages: [verdict.package],
+                reason: "vulnerability_triaged",
+                runner: "install_specific",
+                triage: verdict,
+            });
+        }
+        reportNpmUserOverride(args) {
+            this.safeAudit({
+                occurredAt: Date.now(),
+                packages: args.packages,
+                reason: "vulnerability_user_override",
+                runner: "install_specific",
+                userOverride: {
+                    packages: args.packages,
+                    reason: args.reason,
+                },
+            });
+        }
+        /**
+         * Report silent CVE/quarantine substitutions to the same audit sink as
+         * blocked installs. Best-effort; never fails the install.
+         */
+        maybeReportSubstitutions(substitutions, runner) {
+            for (const entry of substitutions) {
+                this.safeAudit({
+                    reason: "package_substituted",
+                    packages: [`${entry.name}@${entry.fromVersion}`],
                     runner,
                     occurredAt: Date.now(),
+                    substitution: {
+                        fromVersion: entry.fromVersion,
+                        toVersion: entry.toVersion,
+                        reason: entry.reason,
+                    },
                 });
             }
-            catch {
-                // Audit reporting is best-effort and must not affect the install.
+        }
+        /** Mode 2: write gate substitutions into package.json. Audit is the caller's job after install succeeds (same as Mode 1). */
+        async applyDeclaredDependencyUpgrades(remediation) {
+            if (remediation.substitutions.length === 0)
+                return [];
+            const rewritten = await this.enqueueFsOperation("applyPackageJsonSubstitutions", () => applyPackageJsonSubstitutions({
+                appRootDirPath: this.appRootDirPath,
+                logger: getLogger(),
+                substitutions: remediation.substitutions,
+            }));
+            if (rewritten.length === 0)
+                return [];
+            const applied = new Set(rewritten);
+            return remediation.substitutions.filter((entry) => applied.has(entry.name));
+        }
+        async remediateDeclaredDependencies(abortSignal) {
+            // Kill switch / unwired lookup: do not short-circuit registry or rewrite
+            // package.json — startup must behave as pre-gate.
+            if (!this.packageLookup) {
+                return;
             }
+            await this.withAuthFailedRetry(async (registryFetchResult) => {
+                this.maybeShortCircuitForUnreachable(registryFetchResult, []);
+                // Cloud: strip workspace: before Mode 2 dry-run malware scan.
+                await this.maybePreparePackageJsonForCloudNpm();
+                await this.applyDeclaredDependencyUpgrades(await this.maybeRemediateVulnerabilities({
+                    abortSignal,
+                    mode: "all",
+                }));
+            });
         }
         /**
          * Env overlay for AppShell-spawned npm/pnpm installs in the live-edit
@@ -724,11 +902,14 @@ let AppShell = (() => {
                     // was at some point configured with a private registry. See
                     // `maybeShortCircuitForUnreachable` for the full rationale.
                     this.maybeShortCircuitForUnreachable(registryFetchResult, []);
+                    await this.maybePreparePackageJsonForCloudNpm();
+                    const appliedSubstitutions = await this.applyDeclaredDependencyUpgrades(await this.maybeRemediateVulnerabilities({
+                        abortSignal,
+                        mode: "all",
+                    }));
                     const ignoreScripts = shouldIgnoreInstallScripts(registryFetchResult);
                     const isNpm = process.env.SUPERBLOCKS_SERVER_ENV !== "local";
-                    if (isNpm) {
-                        await this.maybePreparePackageJsonForCloudNpm();
-                    }
+                    // prepare already ran above so Mode 2 cloud dry-run sees semver deps.
                     // In csb mock server (local dev) we use pnpm to avoid lockfile / store
                     // conflicts with the surrounding workspace; everywhere else we force npm
                     // so the `--json` error contract — and therefore the registry-blocked
@@ -741,7 +922,7 @@ let AppShell = (() => {
                     const command = ignoreScripts
                         ? `${baseCommand} --ignore-scripts`
                         : baseCommand;
-                    return await new Promise((resolve, reject) => {
+                    await new Promise((resolve, reject) => {
                         exec(command, {
                             cwd: this.appRootDirPath,
                             env: this.installLogEnv(),
@@ -767,6 +948,9 @@ let AppShell = (() => {
                             return resolve();
                         });
                     });
+                    // Audit only after the install succeeds: a selected substitution is
+                    // not an applied substitution if npm fails (same as Mode 1).
+                    this.maybeReportSubstitutions(appliedSubstitutions, "install_all");
                 });
             }
             catch (err) {
@@ -814,6 +998,344 @@ let AppShell = (() => {
                 hasAnyRegistryConfigured: true,
             });
         }
+        /**
+         * POST `/api/v1/security/package-lookup` for a batch of `{name,version}`
+         * pairs. One request — the server cap is 5000. Throws on non-2xx / network
+         * / malformed body so the caller can apply malware fail-closed.
+         */
+        async lookupPackageVulnerabilities(packages) {
+            const deps = this.packageLookup;
+            if (!deps) {
+                return [];
+            }
+            if (packages.length === 0) {
+                return [];
+            }
+            const jwt = await deps.getJwt();
+            const base = deps.baseUrl.replace(/\/$/, "");
+            const url = `${base}/api/v1/security/package-lookup`;
+            const fetchFn = deps.fetch ?? globalThis.fetch;
+            const response = await fetchFn(url, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${jwt}`,
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({ packages }),
+            });
+            if (!response.ok) {
+                throw new Error(`package-lookup returned HTTP ${response.status}`);
+            }
+            const body = await response.json();
+            if (body == null ||
+                typeof body !== "object" ||
+                !("data" in body) ||
+                body.data == null ||
+                typeof body.data !== "object" ||
+                !("results" in body.data) ||
+                !Array.isArray(body.data.results)) {
+                throw new Error("package-lookup response missing data.results");
+            }
+            const results = [];
+            for (const entry of body.data.results) {
+                if (!isPackageLookupResult(entry)) {
+                    throw new Error("package-lookup response contained an off-shape result");
+                }
+                results.push(entry);
+            }
+            const checked = new Set(results.map((result) => `${result.name}@${result.version}`));
+            for (const pkg of packages) {
+                if (!checked.has(`${pkg.name}@${pkg.version}`)) {
+                    throw new Error(`package-lookup response missing result for ${pkg.name}@${pkg.version}`);
+                }
+            }
+            return results;
+        }
+        /**
+         * Mode 1: npm dry-run + lockfile.
+         * Mode 2: `topLevel` is always declared package.json floors (CVE remediations).
+         * Cloud malware tree = floors ∪ package-lock ∪ dry-run (after workspace:
+         * rewrite). Local stays floors-only — pnpm + lingering `workspace:*` mean
+         * full-tree coverage is not available there.
+         */
+        async resolveInstallTree(mode, packages, abortSignal) {
+            if (mode === "all") {
+                const topLevel = [];
+                for (const pkg of packages ?? []) {
+                    const version = declaredRangeFloor(pkg.version);
+                    if (version != null)
+                        topLevel.push({ name: pkg.name, version });
+                }
+                // Local: floors only. Cloud: union lockfile + dry-run for malware.
+                if (process.env.SUPERBLOCKS_SERVER_ENV === "local") {
+                    return { resolves: true, topLevel, tree: topLevel };
+                }
+                const fromLock = await this.readPackagesFromPackageLock();
+                let dryTree = [];
+                try {
+                    dryTree = (await this.resolveTreeViaNpmDryRun([], abortSignal)).tree;
+                }
+                catch (err) {
+                    // Do not continue remediation after cancel.
+                    if (abortSignal?.aborted ||
+                        (err instanceof Error && err.name === "AbortError")) {
+                        throw err;
+                    }
+                    // Unexpected probe failure (not ERESOLVE / error envelope) — still
+                    // malware-scan floors + lockfile instead of aborting the gate.
+                }
+                const byKey = new Map();
+                for (const pkg of [...(fromLock?.tree ?? []), ...dryTree, ...topLevel]) {
+                    byKey.set(`${pkg.name}@${pkg.version}`, pkg);
+                }
+                // Keep resolves:true so a failed dry-run cannot skip floor CVE swaps;
+                // malware still sees whatever floors/lock/dry contributed.
+                return { resolves: true, topLevel, tree: [...byKey.values()] };
+            }
+            const specs = (packages ?? []).map((pkg) => pkg.version ? `${pkg.name}@${pkg.version}` : pkg.name);
+            const resolved = await this.resolveTreeViaNpmDryRun(specs, abortSignal);
+            // Prefer dry-run concrete pins for top-level. Never inject the raw
+            // requested range/`latest` string into the lookup tree — the index
+            // keys on concrete versions, and a range would fail coverage checks.
+            const topLevel = [];
+            for (const pkg of packages ?? []) {
+                // An exact pin is what npm puts at the root, so it needs no resolution —
+                // and looking it up in the dry-run tree risks matching some other copy of
+                // the same name. It stays checkable even when npm cannot resolve the full
+                // tree; the lockfile union below preserves malware coverage for the tree
+                // already on disk.
+                if (pkg.version && semver.valid(pkg.version)) {
+                    topLevel.push({ name: pkg.name, version: pkg.version });
+                    continue;
+                }
+                const fromDry = resolved.topLevel.find((entry) => entry.name === pkg.name);
+                if (fromDry)
+                    topLevel.push(fromDry);
+            }
+            // Lockfile entries come first so already-satisfied installs (empty
+            // dry-run `add`) still malware-scan locked transitives; dry-run pins and
+            // top-level overwrite on collision because they reflect what this
+            // install actually changes.
+            const fromLock = await this.readPackagesFromPackageLock();
+            const byKey = new Map();
+            for (const pkg of [
+                ...(fromLock?.tree ?? []),
+                ...resolved.tree,
+                ...topLevel,
+            ]) {
+                byKey.set(`${pkg.name}@${pkg.version}`, pkg);
+            }
+            return {
+                tree: [...byKey.values()],
+                topLevel,
+                resolves: resolved.resolves,
+            };
+        }
+        async resolveTreeViaNpmDryRun(specs, abortSignal) {
+            const args = [
+                "install",
+                "--dry-run",
+                "--json",
+                "--fund=false",
+                "--audit=false",
+                // `--` so a spec that looks like an option (`--registry=…`,
+                // `--userconfig=…`) is parsed as a package name instead of
+                // reconfiguring the probe: the gate scans the tree this resolves, so a
+                // redirected registry would vouch for packages the real install never
+                // fetches. npm rejects the name and we fail closed.
+                "--",
+                ...specs,
+            ];
+            try {
+                // execFile (no shell) so hostile package specs cannot inject shell
+                // metacharacters into the dry-run probe.
+                const { stdout } = await execFilePromise("npm", args, {
+                    cwd: this.appRootDirPath,
+                    env: this.installLogEnv(),
+                    signal: abortSignal,
+                    maxBuffer: NPM_JSON_MAX_BUFFER,
+                });
+                const parsed = parseNpmJsonStdout(stdout);
+                return this.treeFromNpmDryRunJson(parsed, specs);
+            }
+            catch (error) {
+                const err = error;
+                const combined = `${err.stdout ?? ""}\n${err.stderr ?? ""}\n${err.message ?? ""}`;
+                if (/ERESOLVE|EPEERINVALID/i.test(combined)) {
+                    return { tree: [], topLevel: [], resolves: false };
+                }
+                // Non-zero exit can still carry a usable dry-run body — or an `{ error }`
+                // envelope (EUNSUPPORTEDPROTOCOL / E404 / ETARGET). Treat the latter as
+                // unresolved so the gate fails closed instead of scanning an empty tree.
+                if (err.stdout && err.stdout.includes("{")) {
+                    try {
+                        const parsed = parseNpmJsonStdout(err.stdout);
+                        if (isNpmErrorEnvelope(parsed)) {
+                            return { tree: [], topLevel: [], resolves: false };
+                        }
+                        return this.treeFromNpmDryRunJson(parsed, specs);
+                    }
+                    catch {
+                        // fall through
+                    }
+                }
+                throw error;
+            }
+        }
+        treeFromNpmDryRunJson(parsed, specs) {
+            if (parsed == null || typeof parsed !== "object") {
+                return { tree: [], topLevel: [], resolves: true };
+            }
+            const record = parsed;
+            const tree = [];
+            const root = [];
+            const seen = new Set();
+            const push = (name, version, entryPath) => {
+                if (typeof name !== "string" || typeof version !== "string")
+                    return;
+                if (!name || !version)
+                    return;
+                const key = `${name}@${version}`;
+                if (!seen.has(key)) {
+                    seen.add(key);
+                    tree.push({ name, version });
+                }
+                if (isRootNodeModulesPath(entryPath))
+                    root.push({ name, version });
+            };
+            if (Array.isArray(record.add)) {
+                for (const entry of record.add) {
+                    if (entry == null || typeof entry !== "object")
+                        continue;
+                    const pkg = entry;
+                    push(pkg.name, pkg.version, pkg.path);
+                }
+            }
+            if (Array.isArray(record.change)) {
+                for (const entry of record.change) {
+                    if (entry == null || typeof entry !== "object")
+                        continue;
+                    const change = entry;
+                    if (change.to == null || typeof change.to !== "object")
+                        continue;
+                    const to = change.to;
+                    push(to.name, to.version, to.path);
+                }
+            }
+            const topLevelNames = new Set(specs.map((spec) => {
+                if (spec.startsWith("@")) {
+                    const at = spec.indexOf("@", 1);
+                    return at > 0 ? spec.slice(0, at) : spec;
+                }
+                return spec.split("@")[0] ?? spec;
+            }));
+            // Top-level is the copy npm puts at the app's own `node_modules/<name>`.
+            // A dependency's nested copy shares the requested name but is a different
+            // version, and vouching for it would let the requested one install
+            // unchecked.
+            const topLevel = root.filter((pkg) => topLevelNames.has(pkg.name));
+            return { tree, topLevel, resolves: true };
+        }
+        async readPackagesFromPackageLock() {
+            const lockPath = path.join(this.appRootDirPath, "package-lock.json");
+            let raw;
+            try {
+                raw = await fsReadFile(lockPath, "utf8");
+            }
+            catch {
+                return null;
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch {
+                return null;
+            }
+            if (parsed == null || typeof parsed !== "object") {
+                return null;
+            }
+            const lock = parsed;
+            const tree = [];
+            const seen = new Set();
+            const push = (name, version) => {
+                const key = `${name}@${version}`;
+                if (seen.has(key))
+                    return;
+                seen.add(key);
+                tree.push({ name, version });
+            };
+            if (lock.packages && typeof lock.packages === "object") {
+                for (const [lockPathKey, meta] of Object.entries(lock.packages)) {
+                    if (!meta || typeof meta.version !== "string")
+                        continue;
+                    // Only `node_modules/**` entries are installed packages. `packages[""]`
+                    // (and any workspace root) is first-party code carrying a
+                    // builder-chosen name, so scanning it would block every install by an
+                    // app that happens to be named after a malicious package.
+                    const pathName = packageNameFromLockPath(lockPathKey);
+                    if (!pathName)
+                        continue;
+                    // An aliased install (`"node_modules/alias": { name: "real" }`) fetches
+                    // `meta.name` from the registry; that is the name to scan.
+                    push(typeof meta.name === "string" && meta.name.length > 0
+                        ? meta.name
+                        : pathName, meta.version);
+                }
+            }
+            else if (lock.dependencies && typeof lock.dependencies === "object") {
+                // lockfileVersion 1: nested `dependencies` hold transitive pins.
+                const walkV1 = (deps) => {
+                    if (deps == null || typeof deps !== "object")
+                        return;
+                    for (const [name, meta] of Object.entries(deps)) {
+                        if (meta == null || typeof meta !== "object")
+                            continue;
+                        if (!("version" in meta) || typeof meta.version !== "string") {
+                            continue;
+                        }
+                        push(name, meta.version);
+                        if ("dependencies" in meta &&
+                            meta.dependencies != null &&
+                            typeof meta.dependencies === "object") {
+                            walkV1(meta.dependencies);
+                        }
+                    }
+                };
+                walkV1(lock.dependencies);
+            }
+            return { tree, topLevel: tree, resolves: true };
+        }
+        /**
+         * Vulnerability gate. Mode 1 remediates/blocks top-level CVEs; Mode 2
+         * silently rewrites declared deps (same major) and leaves the rest.
+         * No-op when `packageLookup` is unwired. Index failures → malware fail-closed.
+         */
+        async maybeRemediateVulnerabilities(args) {
+            const { abortSignal, cveUserOverride, mode } = args;
+            if (!this.packageLookup) {
+                return { substitutions: [] };
+            }
+            const packages = mode === "all"
+                ? await readDeclaredDependencies(this.appRootDirPath)
+                : args.packages;
+            return await runVulnerabilityGate({
+                abortSignal,
+                capabilities: {
+                    lookupPackages: async (resolved) => await this.lookupPackageVulnerabilities(resolved),
+                    onIndexUnavailable: ({ error, message }) => {
+                        emitIndexUnavailableMetric();
+                        getLogger().warn(message, getErrorMeta(error));
+                    },
+                    pickQuarantineHoldback: this.packageLookup.pickQuarantineHoldback,
+                    resolveInstallTree: async (resolveArgs) => await this.resolveInstallTree(resolveArgs.mode, resolveArgs.packages, resolveArgs.abortSignal),
+                    resolvePackageSpecs: async (resolveArgs) => await this.resolveTreeViaNpmDryRun(resolveArgs.specs, resolveArgs.abortSignal),
+                },
+                cveUserOverride,
+                mode,
+                packages,
+            });
+        }
         /**
          * Derive the `hasAnyRegistryConfigured` tri-state from the
          * `NpmRegistryFetchResult` that the immediately-preceding
@@ -966,14 +1488,14 @@ let AppShell = (() => {
                     // APPS-4370: short-circuit before any exec when server is unreachable
                     // AND this org's marker says it was previously configured.
                     this.maybeShortCircuitForUnreachable(registryFetchResult, []);
-                    const ignoreScripts = shouldIgnoreInstallScripts(registryFetchResult);
                     // In cloud edit mode, always use npm because pnpm is not available in the container.
                     // The user's project may have pnpm signals (pnpm-lock.yaml, packageManager field)
                     // from local editing, but we must use npm in cloud mode.
                     const isCloudMode = process.env.SUPERBLOCKS_SERVER_ENV !== "local";
                     let packageManagerAgent;
                     if (isCloudMode) {
-                        // Force npm in cloud mode
+                        // Force npm in cloud mode; prepare before Mode 2 so dry-run malware
+                        // scan does not choke on workspace: protocol entries.
                         packageManagerAgent = "npm";
                         await this.maybePreparePackageJsonForCloudNpm();
                     }
@@ -993,6 +1515,11 @@ let AppShell = (() => {
                         }
                         packageManagerAgent = packageManager.agent;
                     }
+                    const appliedSubstitutions = await this.applyDeclaredDependencyUpgrades(await this.maybeRemediateVulnerabilities({
+                        abortSignal,
+                        mode: "all",
+                    }));
+                    const ignoreScripts = shouldIgnoreInstallScripts(registryFetchResult);
                     const isNpm = packageManagerAgent === "npm";
                     const baseInstallArgs = isNpm
                         ? ["--fund=false", "--audit=false", "--json"]
@@ -1014,6 +1541,8 @@ let AppShell = (() => {
                             // default 1 MiB exec buffer on fat dep trees.
                             maxBuffer: NPM_JSON_MAX_BUFFER,
                         });
+                        // Audit only after the install succeeds (same as Mode 1).
+                        this.maybeReportSubstitutions(appliedSubstitutions, "install_all");
                         // On the npm path stdout is a JSON blob; translate to a compact
                         // human-readable summary for the agent, falling back to raw stdout
                         // when the JSON shape drifts.
@@ -1038,7 +1567,7 @@ let AppShell = (() => {
                 this.observeNpmInstall("install_all", capturedFetchResult, outcome, Date.now() - installStart);
             }
         }
-        async installSpecificPackages(packages, abortSignal) {
+        async installSpecificPackages(packages, abortSignal, options) {
             if (!packages || packages.length === 0) {
                 throw new Error("No packages specified for installation");
             }
@@ -1053,10 +1582,10 @@ let AppShell = (() => {
                     // surfaces them to the agent ("we tried to install lodash and the
                     // private registry was unreachable").
                     this.maybeShortCircuitForUnreachable(registryFetchResult, packages.map((pkg) => pkg.version ? `${pkg.name}@${pkg.version}` : pkg.name));
-                    const ignoreScripts = shouldIgnoreInstallScripts(registryFetchResult);
                     // In cloud edit mode, always use npm because pnpm is not available in the container.
                     // The user's project may have pnpm signals (pnpm-lock.yaml, packageManager field)
-                    // from local editing, but we must use npm in cloud mode.
+                    // from local editing, but we must use npm in cloud mode. Prepare before the
+                    // Mode 1 dry-run so leftover workspace: entries cannot break malware coverage.
                     const isCloudMode = process.env.SUPERBLOCKS_SERVER_ENV !== "local";
                     let packageManagerAgent;
                     if (isCloudMode) {
@@ -1079,10 +1608,21 @@ let AppShell = (() => {
                         }
                         packageManagerAgent = packageManager.agent;
                     }
+                    // Malware hard-block on the dry-run resolved tree (top-level +
+                    // transitive) before the real install runs. Mode 1 also returns
+                    // silent CVE substitutions applied to the install argv below.
+                    const remediation = await this.maybeRemediateVulnerabilities({
+                        abortSignal,
+                        cveUserOverride: options?.cveUserOverride,
+                        mode: "specific",
+                        packages,
+                    });
+                    const packagesToInstall = applyPackageSubstitutions(packages, remediation.substitutions);
+                    const ignoreScripts = shouldIgnoreInstallScripts(registryFetchResult);
                     const isNpm = packageManagerAgent === "npm";
                     // Separate regular and dev dependencies
-                    const regularPackages = packages.filter((pkg) => !pkg.dev);
-                    const devPackages = packages.filter((pkg) => pkg.dev);
+                    const regularPackages = packagesToInstall.filter((pkg) => !pkg.dev);
+                    const devPackages = packagesToInstall.filter((pkg) => pkg.dev);
                     const outputs = [];
                     // Install regular dependencies
                     if (regularPackages.length > 0) {
@@ -1146,6 +1686,18 @@ let AppShell = (() => {
                             throw new NpmInstallError(error.stderr || error.message);
                         }
                     }
+                    // Audit only after every install group succeeds: a selected
+                    // substitution is not an applied substitution if npm fails.
+                    this.maybeReportSubstitutions(remediation.substitutions, "install_specific");
+                    // Audited here, not at the tool layer: the gate is what consumed the
+                    // override, and the install has now actually landed.
+                    if (options?.cveUserOverride &&
+                        remediation.userOverridePackages?.length) {
+                        this.reportNpmUserOverride({
+                            packages: remediation.userOverridePackages,
+                            reason: options.cveUserOverride.reason,
+                        });
+                    }
                     return outputs.join("\n");
                 });
             }