@mawesome/npm-vm 0.0.0-alpha.0 → 0.1.0

package/dist/src-NhNG2mnQ.js

@@ -0,0 +1,1798 @@
+import { closeSync, createReadStream, createWriteStream, existsSync, fsyncSync, mkdirSync, mkdtempSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, utimesSync, writeFileSync, writeSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, matchesGlob, posix, relative, resolve, sep, win32 } from "node:path";
+import { createHash, createPublicKey, randomBytes, verify } from "node:crypto";
+import semver from "semver";
+import { homedir, hostname } from "node:os";
+import { execFile, execFileSync } from "node:child_process";
+import { Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { createGunzip } from "node:zlib";
+import { Parser } from "tar";
+import Config from "@npmcli/config";
+import npmDefinitions from "@npmcli/config/lib/definitions/index.js";
+//#region src/errors.ts
+/** Exit codes of `npm-vm` itself and of the shim before npm starts (spec section 10). */
+const EXIT = {
+	ok: 0,
+	problems: 1,
+	partial: 2,
+	resolution: 3,
+	transport: 4,
+	verification: 5,
+	abi: 6,
+	usage: 64
+};
+/** A failure with a message id from spec section 12 and the exit code it maps to. */
+var NpmVmError = class extends Error {
+	name = "NpmVmError";
+	id;
+	exitCode;
+	constructor(id, exitCode, message) {
+		super(message);
+		this.id = id;
+		this.exitCode = exitCode;
+	}
+};
+function isNpmVmError(error) {
+	return error instanceof NpmVmError;
+}
+//#endregion
+//#region src/messages.ts
+/** Message builders for spec section 12; every message names the cause and one fix. */
+/** Every URL in `text` with its user info replaced, so a registry token never reaches a terminal (spec SEC-10). */
+function redactUrls(text) {
+	return text.replace(/\b([a-z][a-z0-9+.-]*:\/\/)([^\s/]*)@/gi, "$1***@");
+}
+function describeSpecs(specs) {
+	return specs.map((spec) => spec.hash ? `${spec.exact}+${spec.hash.algorithm}.${spec.hash.hex.slice(0, 8)}…` : spec.range).join(" or ");
+}
+function engineMessage(version, enginesNode, nodeVersion) {
+	return [`npm ${version} needs Node ${enginesNode}, but the active Node is ${nodeVersion}.`, `Switch Node with \`nvm install <version>\` or \`fnm use <version>\`, or relax the npm range in package.json.`].join("\n");
+}
+function noMatchMessage(specs, file, reason) {
+	return [`No npm version satisfies ${describeSpecs(specs)} (${file}): ${reason}.`, `Run \`npm-vm which\` to see the resolution.`].join("\n");
+}
+function transportMessage(ownVersion, detail) {
+	return [`Cannot download npm: ${ownVersion === null ? "no npm beside the active Node" : `Node's own npm ${ownVersion}`} (${detail}); npm 8 or newer is needed as the transport.`, `Reinstall Node or run \`npm-vm install <version>\` from a Node whose npm works.`].join("\n");
+}
+function keyMessage(keyid) {
+	return [`The registry signed npm with key ${keyid}, which npm-vm does not know.`, `Run \`npm-vm self-update\` to pick up new registry keys.`].join("\n");
+}
+function unsignedMessage(registry, version) {
+	return [`${redactUrls(registry)} serves npm ${version} without a registry signature.`, `Pin a tarball hash in devEngines.packageManager (\`${version}+sha512.<hex>\`) to allow unsigned registries.`].join("\n");
+}
+function integrityMessage(expected, actual, detail) {
+	return [`npm tarball verification failed: ${detail}.`, `Expected ${expected}, got ${actual}. Clear the entry with \`npm-vm cache prune\` and retry.`].join("\n");
+}
+function abiMessage(detail) {
+	return [`npm-vm launcher mismatch: ${detail}.`, `Run \`npx --prefix ~ -y @mawesome/npm-vm setup\` to reinstall the launchers.`].join("\n");
+}
+/** M-LOCKED: names the file, the holder, and the one recovery that is safe for where the holder runs. */
+function lockedMessage(path, holder, live, foreign) {
+	if (holder === null) return `${path} is locked by an unreadable owner. If no npm-vm command is running, delete that file and retry.`;
+	const who = `PID ${holder.pid} on ${holder.host} since ${holder.createdAt || "an unknown time"}`;
+	if (foreign) return [`${path} is locked by ${who}, which cannot be verified from this machine.`, `Confirm on ${holder.host} that no npm-vm command runs, then delete ${path} and retry.`].join("\n");
+	if (live) return `${path} is locked by ${who}, which is still running. Wait for it to finish and retry.`;
+	return `${path} is locked by ${who}, which is no longer running. Delete ${path} and retry.`;
+}
+function provenanceMessage(name, version, detail) {
+	return [`${name}@${version} failed provenance verification: ${detail}.`, "The installed version is unchanged. Retry later, or install the release by hand after checking it at https://www.npmjs.com/package/@mawesome/npm-vm."].join("\n");
+}
+function dirPermsMessage(dir, problem, fix) {
+	return [`${dir} ${problem}.`, `Run \`${fix}\` and retry, or point NPM_VM_HOME at a private directory.`].join("\n");
+}
+function changedMessage(file, what) {
+	return `${file} changed since npm-vm wrote it; left untouched. Remove the ${what} by hand if you still want it gone.`;
+}
+function restartMessage() {
+	return "Restart open terminals and IDEs so they pick up the new PATH.";
+}
+//#endregion
+//#region src/own-npm.ts
+/**
+* Locates Node's own npm from the running binary (spec section 1).
+* The lib dir, not the `bin/npm` link: under `--link` that link is the shim.
+*/
+function ownNpmRoot(execPath, platform = process.platform) {
+	if (platform === "win32") return win32.join(win32.dirname(execPath), "node_modules", "npm");
+	let real = execPath;
+	try {
+		real = realpathSync(execPath);
+	} catch {}
+	return posix.join(posix.dirname(real), "..", "lib", "node_modules", "npm");
+}
+function findOwnNpm(execPath = process.execPath, platform = process.platform) {
+	const root = ownNpmRoot(execPath, platform);
+	const { join } = platform === "win32" ? win32 : posix;
+	const manifest = join(root, "package.json");
+	if (!existsSync(manifest)) return null;
+	let version;
+	try {
+		version = JSON.parse(readFileSync(manifest, "utf8")).version;
+	} catch {
+		return null;
+	}
+	if (typeof version !== "string") return null;
+	return {
+		root,
+		version,
+		cliPath: join(root, "bin", "npm-cli.js"),
+		npxCliPath: join(root, "bin", "npx-cli.js")
+	};
+}
+//#endregion
+//#region src/state/proc.ts
+function powershellPath(env = process.env) {
+	return join(env["SystemRoot"] ?? "C:\\Windows", "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
+}
+const SHELL_DIRS = [
+	"/bin",
+	"/usr/bin",
+	"/usr/local/bin",
+	"/opt/homebrew/bin",
+	"/snap/bin"
+];
+/**
+* An absolute path for a shell to probe (spec SEC-8): the login shell when `$SHELL` is absolute, else system dirs.
+* Never PATH, which inside an npm script starts with `node_modules/.bin`.
+*/
+function shellBinary(shell, env = process.env, platform = process.platform) {
+	const name = shell === "powershell" ? "pwsh" : shell;
+	if (platform === "win32") {
+		const pwsh = join(env["ProgramFiles"] ?? "C:\\Program Files", "PowerShell", "7", "pwsh.exe");
+		return shell === "powershell" && existsSync(pwsh) ? pwsh : null;
+	}
+	const login = env["SHELL"];
+	return [...login !== void 0 && isAbsolute(login) && basename(login) === name ? [login] : [], ...SHELL_DIRS.map((dir) => join(dir, name))].find((candidate) => existsSync(candidate)) ?? null;
+}
+/** The start identity of `pid`, or null when the lookup fails or is ambiguous. */
+function startIdentity(pid, platform = process.platform, env = process.env) {
+	try {
+		if (platform === "linux") {
+			const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+			const start = stat.slice(stat.lastIndexOf(")") + 1).trim().split(/\s+/)[19];
+			return start !== void 0 && /^\d+$/.test(start) ? start : null;
+		}
+		if (platform === "darwin") {
+			const out = execFileSync("/bin/ps", [
+				"-o",
+				"lstart=",
+				"-p",
+				String(pid)
+			], {
+				encoding: "utf8",
+				env: {
+					LC_ALL: "C",
+					PATH: "/usr/bin:/bin"
+				}
+			}).trim();
+			return out === "" || out.includes("\n") ? null : out;
+		}
+		if (platform === "win32") {
+			const out = execFileSync(powershellPath(env), [
+				"-NoProfile",
+				"-NonInteractive",
+				"-Command",
+				`(Get-Process -Id ${pid}).StartTime.ToFileTimeUtc()`
+			], {
+				encoding: "utf8",
+				windowsHide: true
+			}).trim();
+			return /^\d+$/.test(out) ? out : null;
+		}
+	} catch {
+		return null;
+	}
+	return null;
+}
+function ownIdentity(platform, env) {
+	return {
+		pid: process.pid,
+		start: startIdentity(process.pid, platform, env)
+	};
+}
+/**
+* Whether the recorded process still runs: dead only when the PID is gone or its start identity differs.
+* Any failure to look up means live, so nothing ever expires a process that merely cannot be inspected.
+*/
+function isLive(identity, platform = process.platform) {
+	try {
+		process.kill(identity.pid, 0);
+	} catch (error) {
+		if (error.code === "ESRCH") return false;
+		return true;
+	}
+	if (identity.start === null) return true;
+	const current = startIdentity(identity.pid, platform);
+	return current === null || current === identity.start;
+}
+//#endregion
+//#region src/state/lease.ts
+function leasesDir(entry) {
+	return `${entry}.leases`;
+}
+function gatePath(entry) {
+	return `${entry}.prune`;
+}
+function newToken() {
+	return randomBytes(8).toString("hex");
+}
+function ownerRecord(machineId, identity = ownIdentity()) {
+	return {
+		...identity,
+		host: hostname(),
+		machineId,
+		createdAt: (/* @__PURE__ */ new Date()).toISOString()
+	};
+}
+function readOwner(file) {
+	try {
+		const parsed = JSON.parse(readFileSync(file, "utf8"));
+		if (typeof parsed.pid !== "number") return null;
+		return {
+			pid: parsed.pid,
+			start: typeof parsed.start === "string" ? parsed.start : null,
+			host: typeof parsed.host === "string" ? parsed.host : "?",
+			machineId: typeof parsed.machineId === "string" ? parsed.machineId : "?",
+			createdAt: typeof parsed.createdAt === "string" ? parsed.createdAt : ""
+		};
+	} catch {
+		return null;
+	}
+}
+/** A file in the per-machine cache belongs to a dead owner only when PROC-1 says so; unreadable means live. */
+function ownerLive(file) {
+	const owner = readOwner(file);
+	return owner === null ? true : isLive(owner);
+}
+/** Creates a shared lease on `entry`; the file name is unique, so a prune can never delete a live one by mistake. */
+function createLease(entry, owner) {
+	const dir = leasesDir(entry);
+	for (let attempt = 0;; attempt += 1) {
+		mkdirSync(dir, {
+			recursive: true,
+			mode: 448
+		});
+		const path = join(dir, newToken());
+		try {
+			writeFileSync(path, JSON.stringify(owner), {
+				mode: 384,
+				flag: "wx"
+			});
+		} catch (error) {
+			rmSync(path, { force: true });
+			if (error.code === "ENOENT" && attempt < 3) continue;
+			throw error;
+		}
+		return {
+			path,
+			release() {
+				rmSync(path, { force: true });
+			}
+		};
+	}
+}
+/**
+* Whether a lease created before a gate check is still in place (spec LEASE-1).
+* A prune that passed its own lease check first moves the whole leases dir away, taking the file with it.
+*/
+function leaseSurvived(lease) {
+	return existsSync(lease.path);
+}
+function listLeases(entry) {
+	try {
+		return readdirSync(leasesDir(entry)).map((name) => join(leasesDir(entry), name));
+	} catch {
+		return [];
+	}
+}
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+const GATE_WAIT_MS = 5e3;
+/**
+* The runtime's shared lease (spec LEASE-1): lease first, then look for a live prune gate.
+* A live gate means the entry is going away: wait briefly, retry once, else return null so the caller fetches a private entry.
+*/
+async function acquireShared(entry, owner, options = {}) {
+	for (let attempt = 0; attempt < 3; attempt += 1) {
+		const lease = createLease(entry, owner);
+		const gate = gatePath(entry);
+		let gated = false;
+		try {
+			gated = ownerLive(gate);
+		} catch {
+			gated = false;
+		}
+		if (!gated || !gateExists(gate)) {
+			if (leaseSurvived(lease)) return lease;
+			continue;
+		}
+		lease.release();
+		const deadline = Date.now() + (options.waitMs ?? GATE_WAIT_MS);
+		while (Date.now() < deadline && gateExists(gate)) await sleep(50);
+	}
+	return null;
+}
+function gateExists(gate) {
+	try {
+		return readOwner(gate) !== null;
+	} catch {
+		return false;
+	}
+}
+/** Creates the prune gate with O_EXCL; false when another gate exists (there is only ever one prune, so a leftover). */
+function createGate(entry, owner) {
+	try {
+		writeFileSync(gatePath(entry), JSON.stringify(owner), {
+			flag: "wx",
+			mode: 384
+		});
+	} catch (error) {
+		if (error.code === "EEXIST") return false;
+		rmSync(gatePath(entry), { force: true });
+		throw error;
+	}
+	return true;
+}
+function removeGate(entry) {
+	rmSync(gatePath(entry), { force: true });
+}
+//#endregion
+//#region src/spec.ts
+var SpecError = class extends Error {
+	name = "SpecError";
+	field;
+	/** The project's policy for this failure, when the entry declaring it could still be read. */
+	onFail = "error";
+	constructor(field, message) {
+		super(message);
+		this.field = field;
+	}
+};
+const MAX_RANGE_LENGTH = 256;
+const HASH_HEX_LENGTH = {
+	sha512: 128,
+	sha256: 64,
+	sha224: 56
+};
+const ON_FAIL = /* @__PURE__ */ new Set([
+	"ignore",
+	"warn",
+	"error",
+	"download"
+]);
+/**
+* Validates one version string before it reaches a transport argv or a message (spec RES-4).
+* Build metadata other than a well-formed hash suffix is rejected: semver would silently drop it.
+*/
+function parseVersionSpec(raw, field) {
+	if (raw.length > MAX_RANGE_LENGTH) throw new SpecError(field, `${field}: version is longer than ${MAX_RANGE_LENGTH} characters`);
+	const plus = raw.indexOf("+");
+	const range = (plus === -1 ? raw : raw.slice(0, plus)).trim();
+	let hash = null;
+	if (plus !== -1) hash = parseHash(raw.slice(plus + 1), field);
+	if (semver.validRange(range) === null) throw new SpecError(field, `${field}: ${JSON.stringify(raw)} is not a semver range`);
+	const exact = semver.valid(range);
+	if (hash !== null && exact === null) throw new SpecError(field, `${field}: a hash needs an exact version, got ${JSON.stringify(raw)}`);
+	return {
+		range,
+		exact,
+		hash
+	};
+}
+function parseHash(suffix, field) {
+	const match = /^(sha512|sha256|sha224)\.([0-9a-fA-F]+)$/.exec(suffix);
+	if (match === null) throw new SpecError(field, `${field}: unsupported hash suffix ${JSON.stringify(`+${suffix}`)}`);
+	const algorithm = match[1];
+	const hex = match[2].toLowerCase();
+	if (hex.length !== HASH_HEX_LENGTH[algorithm]) throw new SpecError(field, `${field}: ${algorithm} hash must be ${HASH_HEX_LENGTH[algorithm]} hex characters`);
+	return {
+		algorithm,
+		hex
+	};
+}
+function isObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Reads the npm requirements of a parsed `package.json` (spec RES-4).
+* Returns null when the project declares nothing for npm, including when it declares only pnpm or yarn.
+*/
+function parseSpecs(pkg) {
+	if (!isObject(pkg)) return null;
+	const devEngines = pkg["devEngines"];
+	if (isObject(devEngines) && devEngines["packageManager"] !== void 0) {
+		const fromDevEngines = parseDevEngines(devEngines["packageManager"]);
+		if (fromDevEngines !== null) return fromDevEngines;
+	}
+	const packageManager = pkg["packageManager"];
+	if (typeof packageManager === "string" && packageManager.startsWith("npm@")) {
+		const field = "packageManager";
+		return {
+			specs: [parseVersionSpec(packageManager.slice(4), field)],
+			onFail: "error",
+			field
+		};
+	}
+	return null;
+}
+function parseDevEngines(value) {
+	const field = "devEngines.packageManager";
+	const entries = Array.isArray(value) ? value : [value];
+	if (entries.length === 0) return null;
+	const specs = [];
+	const last = entries[entries.length - 1];
+	const onFail = isObject(last) ? parseOnFail(last, field) : "error";
+	try {
+		for (const entry of entries) {
+			if (!isObject(entry)) throw new SpecError(field, `${field}: every entry must be an object`);
+			if (entry["name"] !== "npm") continue;
+			const version = entry["version"];
+			if (version === void 0) specs.push({
+				range: "*",
+				exact: null,
+				hash: null
+			});
+			else if (typeof version === "string") specs.push(parseVersionSpec(version, field));
+			else throw new SpecError(field, `${field}: version must be a string`);
+		}
+	} catch (error) {
+		if (error instanceof SpecError) error.onFail = onFail;
+		throw error;
+	}
+	if (specs.length === 0) return null;
+	return {
+		specs,
+		onFail,
+		field: "devEngines"
+	};
+}
+function parseOnFail(entry, field) {
+	const onFail = entry.onFail;
+	if (onFail === void 0) return "error";
+	if (typeof onFail !== "string" || !ON_FAIL.has(onFail)) throw new SpecError(field, `${field}: onFail must be ignore, warn, error or download`);
+	return onFail;
+}
+/** Whether a concrete version satisfies the spec's range, hash aside (spec RES-5 and RES-6). */
+function matchesRange(version, spec) {
+	return semver.satisfies(version, spec.range);
+}
+//#endregion
+//#region src/select.ts
+function engineAccepts(candidate, nodeVersion) {
+	return candidate.enginesNode === null || semver.satisfies(nodeVersion, candidate.enginesNode, { includePrerelease: true });
+}
+function hashAccepts(candidate, spec) {
+	if (spec.hash === null) return candidate.keyid !== null;
+	if (spec.hash.algorithm === "sha512") return sriHex(candidate.integrity) === spec.hash.hex;
+	if (candidate.digests === void 0 || candidate.digests === null) return true;
+	return candidate.digests[spec.hash.algorithm] === spec.hash.hex;
+}
+/** The hex digest of a `sha512-<base64>` SRI string, or null for any other form. */
+function sriHex(integrity) {
+	const match = /^sha512-([A-Za-z0-9+/=]+)$/.exec(integrity.trim());
+	return match === null ? null : Buffer.from(match[1], "base64").toString("hex");
+}
+/** Whether Node's own npm satisfies a spec without a hash (spec RES-5). */
+function ownNpmSatisfies(ownVersion, specs) {
+	return specs.some((spec) => spec.hash === null && matchesRange(ownVersion, spec));
+}
+/**
+* Picks the highest candidate matching any spec and the active Node (spec RES-6), cached first.
+* Returns the reason when nothing fits, distinguishing an `engines.node` exclusion from no match at all.
+*/
+function selectCandidate(specs, candidates, nodeVersion) {
+	let best = null;
+	let excluded = null;
+	for (const candidate of candidates) {
+		const matching = specs.filter((entry) => matchesRange(candidate.version, entry) && hashAccepts(candidate, entry));
+		if (matching.length === 0) continue;
+		if (!engineAccepts(candidate, nodeVersion)) {
+			if (excluded === null || semver.gt(candidate.version, excluded.version)) excluded = candidate;
+			continue;
+		}
+		if (best === null || semver.gt(candidate.version, best.candidate.version)) best = {
+			candidate,
+			hashes: matching.some((entry) => entry.hash === null) ? [] : matching.flatMap((entry) => entry.hash === null ? [] : [entry.hash])
+		};
+	}
+	if (best !== null) return {
+		kind: "selected",
+		selection: best
+	};
+	if (excluded !== null) return {
+		kind: "failed",
+		failure: {
+			kind: "engine",
+			version: excluded.version,
+			enginesNode: excluded.enginesNode ?? "*"
+		}
+	};
+	return {
+		kind: "failed",
+		failure: {
+			kind: "nomatch",
+			reason: "no published version matches"
+		}
+	};
+}
+//#endregion
+//#region src/install/verify.ts
+/** Every digest a spec or the registry may ask for, in one pass over the file. */
+async function fileDigests(file) {
+	const sha512 = createHash("sha512");
+	const sha256 = createHash("sha256");
+	const sha224 = createHash("sha224");
+	await pipeline(createReadStream(file), new Transform({ transform(chunk, _encoding, callback) {
+		sha512.update(chunk);
+		sha256.update(chunk);
+		sha224.update(chunk);
+		callback();
+	} }));
+	const sha512Digest = sha512.digest();
+	return {
+		sha512: `sha512-${sha512Digest.toString("base64")}`,
+		sha512hex: sha512Digest.toString("hex"),
+		sha256hex: sha256.digest("hex"),
+		sha224hex: sha224.digest("hex")
+	};
+}
+function integrityFailure(expected, actual, detail) {
+	return new NpmVmError("M-INTEGRITY", EXIT.verification, integrityMessage(expected, actual, detail));
+}
+/** The tarball must match the registry's integrity and, when the project pins hashes, one of them (spec SEC-2). */
+function checkIntegrity(digests, integrity, hashes) {
+	if (digests.sha512 !== integrity.trim()) throw integrityFailure(integrity, digests.sha512, "the tarball does not match the registry integrity");
+	if (hashes.length === 0) return;
+	const actual = {
+		sha512: digests.sha512hex,
+		sha256: digests.sha256hex,
+		sha224: digests.sha224hex
+	};
+	if (!hashes.some((hash) => actual[hash.algorithm] === hash.hex)) {
+		const [first] = hashes;
+		throw integrityFailure(`${first.algorithm}.${first.hex}`, `${first.algorithm}.${actual[first.algorithm]}`, "the tarball does not match the pinned hash");
+	}
+}
+/**
+* Checks the registry signatures over `name@version:integrity` against the pinned keyring (spec SEC-1).
+* Returns the key id that verified; throws M-KEY for an unknown key and M-UNSIGNED when no signature is usable.
+*/
+async function verifySignatures(input) {
+	if (input.signatures.length === 0) {
+		if (input.pinned) return null;
+		throw new NpmVmError("M-UNSIGNED", EXIT.verification, unsignedMessage(input.registry, input.version));
+	}
+	const payload = Buffer.from(`${input.name}@${input.version}:${input.integrity}`, "utf8");
+	let unknown = null;
+	for (const signature of input.signatures) {
+		const key = input.keys.find((entry) => entry.keyid === signature.keyid);
+		if (key === void 0) {
+			unknown ??= signature.keyid;
+			continue;
+		}
+		if (key.revoked === true || !await keyCurrent(key, input.publishedAt)) continue;
+		const publicKey = createPublicKey({
+			key: Buffer.from(key.key, "base64"),
+			format: "der",
+			type: "spki"
+		});
+		if (verify("sha256", payload, publicKey, Buffer.from(signature.sig, "base64"))) return key.keyid;
+	}
+	if (unknown !== null) throw new NpmVmError("M-KEY", EXIT.verification, keyMessage(unknown));
+	throw new NpmVmError("M-UNSIGNED", EXIT.verification, unsignedMessage(input.registry, input.version));
+}
+/** An expired key still vouches for versions published before it expired; an unknown time fails closed. */
+async function keyCurrent(key, publishedAt) {
+	if (key.expires === null) return true;
+	const published = await publishedAt();
+	return published !== null && Date.parse(published) < Date.parse(key.expires);
+}
+const DEFAULT_LIMITS = {
+	maxEntries: 1e4,
+	maxBytes: 268435456
+};
+function unsafe(detail) {
+	return integrityFailure("a safe npm tarball", "an unsafe entry", detail);
+}
+/** The destination-relative path of a tarball entry, or a thrown M-INTEGRITY for anything outside `package/` (spec SEC-3). */
+function entryRelativePath(path) {
+	if (path.includes("\\") || [...path].some((char) => char.charCodeAt(0) < 32 || char.charCodeAt(0) === 127)) throw unsafe(`entry name contains a control character or backslash: ${JSON.stringify(path)}`);
+	if (path.startsWith("/") || /^[A-Za-z]:/.test(path)) throw unsafe(`absolute entry name: ${path}`);
+	const segments = path.split("/").filter((segment) => segment !== "" && segment !== ".");
+	if (segments.includes("..")) throw unsafe(`entry name climbs out of the archive: ${path}`);
+	if (segments[0] !== "package") throw unsafe(`entry outside package/: ${path}`);
+	return segments.length === 1 ? "" : posix.join(...segments.slice(1));
+}
+/**
+* Extracts regular files and directories under `package/` into `dest`, rejecting everything else (spec SEC-3).
+* Modes are `0644` or `0755` by the owner exec bit; ownership and extended attributes are ignored.
+*/
+async function safeExtract(tarball, dest, limits = DEFAULT_LIMITS) {
+	let entries = 0;
+	let bytes = 0;
+	let decompressed = 0;
+	const writes = [];
+	const parser = new Parser({ strict: true });
+	let aborted = null;
+	const abort = (error) => {
+		aborted ??= error;
+		parser.abort(error);
+	};
+	parser.on("entry", (entry) => {
+		try {
+			entries += 1;
+			bytes += entry.size;
+			if (entries > limits.maxEntries) throw unsafe(`more than ${limits.maxEntries} entries`);
+			if (bytes > limits.maxBytes) throw unsafe(`more than ${limits.maxBytes} bytes`);
+			const relative = entryRelativePath(entry.path);
+			const target = relative === "" ? dest : join(dest, relative);
+			if (entry.type === "Directory") {
+				mkdirSync(target, {
+					recursive: true,
+					mode: 493
+				});
+				entry.resume();
+				return;
+			}
+			if (entry.type !== "File" || relative === "") throw unsafe(`${entry.type} entry: ${entry.path}`);
+			mkdirSync(dirname(target), {
+				recursive: true,
+				mode: 493
+			});
+			const mode = ((entry.mode ?? 420) & 64) === 0 ? 420 : 493;
+			writes.push(pipeline(entry, createWriteStream(target, { mode })));
+		} catch (error) {
+			abort(error);
+		}
+	});
+	const counter = new Transform({ transform(chunk, _encoding, callback) {
+		decompressed += chunk.length;
+		if (decompressed > limits.maxBytes) {
+			callback(unsafe(`more than ${limits.maxBytes} bytes after decompression`));
+			return;
+		}
+		callback(null, chunk);
+	} });
+	const done = new Promise((resolve, reject) => {
+		parser.on("end", () => resolve());
+		parser.on("error", (error) => reject(error));
+	});
+	done.catch(() => void 0);
+	try {
+		await pipeline(createReadStream(tarball), createGunzip(), counter, parser);
+		await done;
+		await Promise.all(writes);
+	} catch (error) {
+		await Promise.allSettled(writes);
+		throw aborted ?? (error instanceof NpmVmError ? error : unsafe(`cannot read the tarball: ${error.message}`));
+	}
+	if (aborted !== null) throw aborted;
+}
+const VERIFIED_FILE = ".verified";
+function writeVerified(dir, verified) {
+	writeFileSync(join(dir, VERIFIED_FILE), JSON.stringify(verified), { mode: 384 });
+}
+function readVerified(dir) {
+	try {
+		const parsed = JSON.parse(readFileSync(join(dir, VERIFIED_FILE), "utf8"));
+		if (typeof parsed.version !== "string" || typeof parsed.integrity !== "string") return null;
+		if (typeof parsed.sha256 !== "string" || typeof parsed.sha224 !== "string") return null;
+		return {
+			version: parsed.version,
+			integrity: parsed.integrity,
+			keyid: typeof parsed.keyid === "string" ? parsed.keyid : null,
+			sha256: parsed.sha256,
+			sha224: parsed.sha224,
+			verifiedAt: typeof parsed.verifiedAt === "string" ? parsed.verifiedAt : ""
+		};
+	} catch {
+		return null;
+	}
+}
+/** `<version>-<16 hex of the integrity>`: two registries serving different bytes get two entries (spec SEC-4). */
+function entryName(version, integrity) {
+	const hex = sriHex(integrity);
+	if (hex === null) throw new Error(`not a sha512 integrity: ${integrity}`);
+	return `${version}-${hex.slice(0, 16)}`;
+}
+/** Where verified entries are staged before the rename into `npm/`: same filesystem, so the rename stays atomic. */
+function stagingDir(cacheRoot) {
+	return join(cacheRoot, "staging");
+}
+function canonicalEntry(cacheRoot, version, integrity) {
+	return join(cacheRoot, "npm", entryName(version, integrity));
+}
+function privateEntry(canonical, token) {
+	return `${canonical}.${token}`;
+}
+/** Whether a directory name under `npm/` is an entry rather than a lease dir, a gate or a deletion in progress. */
+function isEntryName(name) {
+	return /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?-[0-9a-f]{16}(?:\.[0-9a-f]{16})?$/.test(name);
+}
+function readManifest$1(dir) {
+	try {
+		const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+		const engines = pkg["engines"];
+		const node = typeof engines === "object" && engines !== null ? engines["node"] : void 0;
+		return {
+			name: pkg["name"],
+			version: pkg["version"],
+			enginesNode: typeof node === "string" ? node : null
+		};
+	} catch {
+		return null;
+	}
+}
+/**
+* Whether an entry may run (spec SEC-5): verified for this integrity, owned by the current user,
+* and holding the npm it claims. Never deletes anything.
+*/
+function validateEntry(entryPath, integrity) {
+	try {
+		const stat = statSync(entryPath);
+		if (!stat.isDirectory() || process.getuid !== void 0 && stat.uid !== process.getuid()) return false;
+	} catch {
+		return false;
+	}
+	const verified = readVerified(entryPath);
+	if (verified === null || verified.integrity !== integrity) return false;
+	const manifest = readManifest$1(entryPath);
+	return manifest !== null && manifest.name === "npm" && manifest.version === verified.version;
+}
+/** Every verified entry in the cache as a candidate, whatever its validity; use-time validation decides. */
+function listEntries(cacheRoot, keys = []) {
+	let names;
+	try {
+		names = readdirSync(join(cacheRoot, "npm"));
+	} catch {
+		return [];
+	}
+	const candidates = [];
+	for (const name of names) {
+		if (!isEntryName(name)) continue;
+		const entryPath = join(cacheRoot, "npm", name);
+		const verified = readVerified(entryPath);
+		const manifest = readManifest$1(entryPath);
+		if (verified === null || manifest === null || manifest.version !== verified.version) continue;
+		if (verified.keyid !== null && keys.some((key) => key.keyid === verified.keyid && key.revoked === true)) continue;
+		candidates.push({
+			version: verified.version,
+			enginesNode: manifest.enginesNode,
+			integrity: verified.integrity,
+			entryPath,
+			signatures: null,
+			keyid: verified.keyid,
+			digests: {
+				sha256: verified.sha256,
+				sha224: verified.sha224
+			}
+		});
+	}
+	return candidates;
+}
+function isCollision(error) {
+	const code = error.code;
+	return code === "EEXIST" || code === "ENOTEMPTY" || code === "EPERM" || code === "EISDIR";
+}
+/**
+* Moves a verified temp dir into the cache under a lease (spec SEC-4). The lease exists before the
+* rename, so a prune never sees the entry without it; a lost race reuses or sidesteps the winner's entry.
+*/
+function publishEntry(tempDir, canonical, integrity, owner) {
+	const lease = createLease(canonical, owner);
+	if (existsSync(gatePath(canonical)) && ownerLive(gatePath(canonical))) {
+		lease.release();
+		return publishPrivately(tempDir, canonical, owner);
+	}
+	if (!leaseSurvived(lease)) return publishEntry(tempDir, canonical, integrity, owner);
+	try {
+		renameSync(tempDir, canonical);
+		return {
+			entryPath: canonical,
+			lease
+		};
+	} catch (error) {
+		if (!isCollision(error)) {
+			lease.release();
+			throw error;
+		}
+	}
+	if (validateEntry(canonical, integrity)) {
+		rmSync(tempDir, {
+			recursive: true,
+			force: true
+		});
+		return {
+			entryPath: canonical,
+			lease
+		};
+	}
+	lease.release();
+	return publishPrivately(tempDir, canonical, owner);
+}
+function publishPrivately(tempDir, canonical, owner) {
+	for (;;) {
+		const entryPath = privateEntry(canonical, newToken());
+		const privateLease = createLease(entryPath, owner);
+		if (existsSync(gatePath(entryPath)) && ownerLive(gatePath(entryPath))) {
+			privateLease.release();
+			continue;
+		}
+		if (!leaseSurvived(privateLease)) continue;
+		try {
+			renameSync(tempDir, entryPath);
+		} catch (error) {
+			privateLease.release();
+			throw error;
+		}
+		return {
+			entryPath,
+			lease: privateLease
+		};
+	}
+}
+//#endregion
+//#region src/state/atomic.ts
+const RETRY_CODES = /* @__PURE__ */ new Set([
+	"EBUSY",
+	"EPERM",
+	"EACCES"
+]);
+const RETRY_LIMIT_MS = 5e3;
+function sleepSync(ms) {
+	Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/**
+* Runs a file operation, retrying Windows sharing violations with backoff for up to 5 s (spec MUT-3).
+* Elsewhere the same codes are real permission errors and surface at once.
+*/
+function withSharingRetry(operation, platform = process.platform, limitMs = RETRY_LIMIT_MS) {
+	const started = Date.now();
+	let delay = 20;
+	for (;;) try {
+		return operation();
+	} catch (error) {
+		const code = error.code ?? "";
+		if (platform !== "win32" || !RETRY_CODES.has(code) || Date.now() - started + delay > limitMs) throw error;
+		sleepSync(delay);
+		delay = Math.min(delay * 2, 500);
+	}
+}
+/** Writes `content` to `path` through a temp file in the same dir, fsynced and renamed into place. */
+function atomicWrite(path, content, mode = 420) {
+	const dir = dirname(path);
+	mkdirSync(dir, { recursive: true });
+	const temp = join(dir, `.${newToken()}.tmp`);
+	try {
+		const fd = openSync(temp, "wx", mode);
+		try {
+			const buffer = typeof content === "string" ? Buffer.from(content, "utf8") : content;
+			for (let offset = 0; offset < buffer.length;) {
+				const written = writeSync(fd, buffer, offset, buffer.length - offset);
+				if (written <= 0) throw new Error(`short write to ${temp}: ${offset} of ${buffer.length} bytes`);
+				offset += written;
+			}
+			fsyncSync(fd);
+		} finally {
+			closeSync(fd);
+		}
+		withSharingRetry(() => renameSync(temp, path));
+	} catch (error) {
+		rmSync(temp, { force: true });
+		throw error;
+	}
+}
+/** Renames with the Windows retry; a cross-device rename is not retried, it is a layout error. */
+function atomicRename(from, to) {
+	withSharingRetry(() => renameSync(from, to));
+}
+function removeWithRetry(path) {
+	withSharingRetry(() => rmSync(path, {
+		recursive: true,
+		force: true
+	}));
+}
+//#endregion
+//#region src/state/prune.ts
+const USED_SUFFIX = ".used";
+/** Records a resolution of `entry` for the prune age, in a sidecar so the entry itself stays untouched. */
+function touchUsed(entry) {
+	const marker = `${entry}${USED_SUFFIX}`;
+	try {
+		const now = /* @__PURE__ */ new Date();
+		utimesSync(marker, now, now);
+	} catch {
+		writeFileSync(marker, "", { flag: "a" });
+	}
+}
+function lastUsed(entry) {
+	try {
+		return statSync(`${entry}${USED_SUFFIX}`).mtimeMs;
+	} catch {
+		return null;
+	}
+}
+/** Why one entry would go, or null to keep it. */
+function pruneReason(cacheRoot, name, options) {
+	const entry = join(cacheRoot, "npm", name);
+	if (name.includes(".deleting.")) return "leftover";
+	if (!isEntryName(name)) return null;
+	const verified = readVerified(entry);
+	if (verified === null || !validateEntry(entry, verified.integrity)) return "invalid";
+	if (/\.[0-9a-f]{16}$/.test(name) && !listLeases(entry).some((lease) => ownerLive(lease))) return "orphan-private";
+	const used = lastUsed(entry);
+	return (options.now ?? Date.now()) - (used ?? statSync(entry).mtimeMs) > options.maxAgeMs ? "stale" : null;
+}
+/**
+* Removes one entry the exclusive way (spec LEASE-1): gate, drop dead leases, bail on a live one, rename aside, drop the gate, delete.
+* After the gate is gone nothing here touches the entry's paths again.
+*/
+function pruneEntry(entry, owner) {
+	if (existsSync(gatePath(entry)) && !ownerLive(gatePath(entry))) removeGate(entry);
+	if (!createGate(entry, owner)) return false;
+	for (const lease of listLeases(entry)) if (!ownerLive(lease)) rmSync(lease, { force: true });
+	if (listLeases(entry).length > 0) {
+		removeGate(entry);
+		return false;
+	}
+	const token = newToken();
+	const deletingEntry = `${entry}.deleting.${token}`;
+	const deletingLeases = `${entry}.leases.deleting.${token}`;
+	if (existsSync(entry)) atomicRename(entry, deletingEntry);
+	if (existsSync(leasesDir(entry))) atomicRename(leasesDir(entry), deletingLeases);
+	removeGate(entry);
+	removeWithRetry(deletingEntry);
+	removeWithRetry(deletingLeases);
+	rmSync(`${entry}${USED_SUFFIX}`, { force: true });
+	return true;
+}
+const STAGING_MAX_AGE_MS = 864e5;
+/** Work dirs a crashed extraction left under `staging/`; a live one is never a day old. */
+function pruneStaging(cacheRoot, now) {
+	let names;
+	try {
+		names = readdirSync(stagingDir(cacheRoot));
+	} catch {
+		return;
+	}
+	for (const name of names) {
+		const dir = join(stagingDir(cacheRoot), name);
+		try {
+			if (now - statSync(dir).mtimeMs > STAGING_MAX_AGE_MS) removeWithRetry(dir);
+		} catch {}
+	}
+}
+/** Prunes the whole cache; the caller holds the exclusive lock (MUT-1) so only one prune ever runs. */
+function pruneCache(cacheRoot, owner, options) {
+	const report = {
+		removed: [],
+		kept: [],
+		skipped: []
+	};
+	pruneStaging(cacheRoot, options.now ?? Date.now());
+	let names;
+	try {
+		names = readdirSync(join(cacheRoot, "npm"));
+	} catch {
+		return report;
+	}
+	for (const name of names) {
+		const entry = join(cacheRoot, "npm", name);
+		if (name.endsWith(".leases") && existsSync(entry) && !existsSync(entry.slice(0, -7))) {
+			(pruneEntry(entry.slice(0, -7), owner) ? report.removed : report.skipped).push(name);
+			continue;
+		}
+		if (name.endsWith(".prune") && !existsSync(entry.slice(0, -6)) && !ownerLive(entry)) {
+			rmSync(entry, { force: true });
+			report.removed.push(name);
+			continue;
+		}
+		const reason = pruneReason(cacheRoot, name, options);
+		if (reason === null) {
+			if (isEntryName(name)) report.kept.push(name);
+			continue;
+		}
+		if (reason === "leftover") {
+			removeWithRetry(entry);
+			report.removed.push(name);
+			continue;
+		}
+		if (pruneEntry(entry, owner)) report.removed.push(name);
+		else report.skipped.push(name);
+	}
+	return report;
+}
+//#endregion
+//#region src/setup/home.ts
+function localAppData(env) {
+	return env["LOCALAPPDATA"] ?? join(homedir(), "AppData", "Local");
+}
+function defaultHome(env, platform = process.platform) {
+	if (platform === "win32") return join(localAppData(env), "npm-vm");
+	return join(env["XDG_DATA_HOME"] || join(homedir(), ".local", "share"), "npm-vm");
+}
+function cacheBase(env, platform = process.platform) {
+	if (platform === "win32") return join(localAppData(env), "npm-vm-cache");
+	return join(env["XDG_CACHE_HOME"] || join(homedir(), ".cache"), "npm-vm");
+}
+function platformId(platform, env) {
+	try {
+		if (platform === "linux") {
+			for (const file of ["/etc/machine-id", "/var/lib/dbus/machine-id"]) try {
+				const id = readFileSync(file, "utf8").trim();
+				if (id !== "") return id;
+			} catch {}
+			return null;
+		}
+		if (platform === "darwin") {
+			const out = execFileSync("/usr/sbin/ioreg", [
+				"-rd1",
+				"-c",
+				"IOPlatformExpertDevice"
+			], {
+				encoding: "utf8",
+				env: { PATH: "/usr/bin:/bin:/usr/sbin:/sbin" }
+			});
+			return /"IOPlatformUUID"\s*=\s*"([^"]+)"/.exec(out)?.[1] ?? null;
+		}
+		if (platform === "win32") {
+			const reg = join(env["SystemRoot"] ?? "C:\\Windows", "System32", "reg.exe");
+			const out = execFileSync(reg, [
+				"query",
+				"HKLM\\SOFTWARE\\Microsoft\\Cryptography",
+				"/v",
+				"MachineGuid"
+			], { encoding: "utf8" });
+			return /MachineGuid\s+REG_SZ\s+(\S+)/.exec(out)?.[1] ?? null;
+		}
+	} catch {}
+	return null;
+}
+/** The hashed machine id, or a hashed hostname when the platform id is unreadable. */
+function readMachineId(env = process.env, platform = process.platform) {
+	const raw = platformId(platform, env);
+	const source = raw ?? hostname();
+	return {
+		id: createHash("sha256").update(source).digest("hex").slice(0, 16),
+		fallback: raw === null
+	};
+}
+function resolveDirs(env = process.env, home = env["NPM_VM_HOME"] || defaultHome(env), platform = process.platform, machine = readMachineId(env, platform)) {
+	const absoluteHome = resolve(home);
+	const state = join(absoluteHome, "state");
+	return {
+		home: absoluteHome,
+		cache: join(cacheBase(env, platform), machine.id),
+		state,
+		tmp: join(state, "tmp"),
+		journal: join(state, "journal"),
+		machine
+	};
+}
+//#endregion
+//#region src/install/config.ts
+const DROPPED = /* @__PURE__ */ new Set(["NODE_OPTIONS", "NODE_EXTRA_CA_CERTS"]);
+/** Proxy settings reach the transport only from the user and global npm config (spec DL-2), never the env. */
+const PROXY_VARS = /^(https?_proxy|all_proxy|no_proxy|proxy)$/i;
+/** The env without anything that would steer npm or Node: `npm_config_*`, proxies, `NODE_OPTIONS`, `NODE_EXTRA_CA_CERTS`. */
+function sanitizeEnv(env) {
+	const clean = {};
+	for (const [key, value] of Object.entries(env)) {
+		if (/^npm_config_/i.test(key) || DROPPED.has(key.toUpperCase()) || PROXY_VARS.test(key)) continue;
+		clean[key] = value;
+	}
+	return clean;
+}
+function optionalString(value) {
+	const text = Array.isArray(value) ? value.map(String).filter((item) => item !== "").join(",") : value;
+	return typeof text === "string" && text !== "" ? text : null;
+}
+/**
+* Loads npm's config the way npm does, minus the project: `cwd` is an empty dir under the home,
+* the env is sanitized and nothing is printed. Credentials come only from `getCredentialsByURI`.
+*/
+async function loadNpmConfig(own, env, cwd, nodePath = process.execPath) {
+	const { definitions, shorthands, flatten, nerfDarts } = npmDefinitions;
+	const config = new Config({
+		definitions,
+		shorthands,
+		flatten,
+		nerfDarts,
+		npmPath: own.root,
+		argv: [
+			nodePath,
+			own.cliPath,
+			"--location=global"
+		],
+		execPath: nodePath,
+		env: { ...sanitizeEnv(env) },
+		cwd,
+		excludeNpmCwd: true
+	});
+	await config.load();
+	const registry = String(config.get("registry"));
+	const ca = config.get("ca");
+	return {
+		registry,
+		userconfig: String(config.get("userconfig")),
+		globalconfig: String(config.get("globalconfig")),
+		cache: String(config.get("cache")),
+		credentials: config.getCredentialsByURI(registry),
+		httpsProxy: optionalString(config.get("https-proxy")),
+		proxy: optionalString(config.get("proxy")),
+		noproxy: optionalString(config.get("noproxy")),
+		ca: Array.isArray(ca) ? ca.map(String) : typeof ca === "string" ? [ca] : null,
+		cafile: optionalString(config.get("cafile")),
+		strictSsl: config.get("strict-ssl") !== false
+	};
+}
+//#endregion
+//#region src/install/fetch.ts
+const MIN_TRANSPORT = "8.0.0";
+const MAX_OUTPUT = 268435456;
+/** Whether Node's own npm can serve as the transport (spec DL-1). */
+function transportUsable(own) {
+	return own !== null && semver.gte(own.version, MIN_TRANSPORT);
+}
+/** A fresh private working dir under `state/tmp/`, never the shared system temp dir (spec DL-2). */
+function newWorkDir(tmpRoot) {
+	mkdirSync(tmpRoot, {
+		recursive: true,
+		mode: 448
+	});
+	return mkdtempSync(join(tmpRoot, "work-"));
+}
+/**
+* Runs Node's own npm as the download transport, isolated from the project (spec DL-1, DL-2).
+* Every call runs in its own empty working dir, with that dir as the prefix and the user and global config named explicitly.
+*/
+var Transport = class {
+	#own;
+	#config;
+	#env;
+	#tmpRoot;
+	#nodePath;
+	constructor(own, config, env, tmpRoot, nodePath = process.execPath) {
+		this.#own = own;
+		this.#config = config;
+		this.#env = sanitizeEnv(env);
+		this.#tmpRoot = tmpRoot;
+		this.#nodePath = nodePath;
+	}
+	/** Versions of npm matching `range`, newest last as npm lists them; an unmatched range is an empty list. */
+	view(range) {
+		return this.viewPackage("npm", range);
+	}
+	/** The same for any package, used by self-update for its own package. */
+	async viewPackage(name, range) {
+		const output = await this.#run([
+			"view",
+			`${name}@${range}`,
+			"version",
+			"engines",
+			"dist"
+		], true);
+		if (output === null) return [];
+		return asList(output).flatMap((item) => {
+			const version = readString(item, "version");
+			const dist = readObject(item, "dist");
+			const integrity = dist === null ? null : readString(dist, "integrity");
+			const tarball = dist === null ? null : readString(dist, "tarball");
+			if (version === null || integrity === null || tarball === null) return [];
+			const engines = readObject(item, "engines");
+			const signatures = (dist === null ? null : dist["signatures"]) ?? [];
+			const attestations = dist === null ? null : readObject(dist, "attestations");
+			return [{
+				version,
+				enginesNode: engines === null ? null : readString(engines, "node"),
+				integrity,
+				tarball,
+				signatures: Array.isArray(signatures) ? signatures.filter(isSignature) : [],
+				attestationsUrl: attestations === null ? null : readString(attestations, "url")
+			}];
+		});
+	}
+	/** Publication time per version, used only to judge signatures by expired keys. */
+	async times() {
+		const output = await this.#run([
+			"view",
+			"npm",
+			"time"
+		], true);
+		const map = output === null ? null : asList(output)[0] ?? null;
+		const times = {};
+		if (map !== null && typeof map === "object") {
+			for (const [version, time] of Object.entries(map)) if (typeof time === "string") times[version] = time;
+		}
+		return times;
+	}
+	/** Downloads one npm version's tarball into `dest` through `npm pack`. */
+	pack(version, dest) {
+		return this.packPackage("npm", version, dest);
+	}
+	async packPackage(name, version, dest) {
+		const item = asList(await this.#run([
+			"pack",
+			`${name}@${version}`,
+			`--pack-destination=${dest}`
+		], false)).flatMap((item) => readString(item, "filename") === null ? asList(Object.values(item)) : [item]).find((candidate) => readString(candidate, "filename") !== null) ?? null;
+		const filename = item === null ? null : readString(item, "filename");
+		const integrity = item === null ? null : readString(item, "integrity");
+		if (filename === null || integrity === null) throw this.#failure(`npm pack returned no tarball for ${name}@${version}`);
+		return {
+			file: join(dest, filename),
+			integrity
+		};
+	}
+	#failure(detail) {
+		return new NpmVmError("M-TRANSPORT", EXIT.transport, transportMessage(this.#own.version, detail));
+	}
+	/** Runs npm with the isolation flags; returns parsed JSON, or null for a 404 when `missingIsEmpty`. */
+	async #run(args, missingIsEmpty) {
+		const cwd = newWorkDir(this.#tmpRoot);
+		const argv = [
+			this.#own.cliPath,
+			...args,
+			"--json",
+			"--ignore-scripts",
+			"--loglevel=error",
+			"--replace-registry-host=always",
+			...proxyFlags(this.#config),
+			"--fetch-retry-mintimeout=1000",
+			"--fetch-retry-maxtimeout=10000",
+			`--prefix=${cwd}`,
+			`--cache=${this.#config.cache}`,
+			`--userconfig=${this.#config.userconfig}`,
+			`--globalconfig=${this.#config.globalconfig}`
+		];
+		try {
+			const { stdout: output } = await new Promise((resolve, reject) => {
+				execFile(this.#nodePath, argv, {
+					cwd,
+					env: this.#env,
+					maxBuffer: MAX_OUTPUT,
+					timeout: 3e5,
+					windowsHide: true
+				}, (error, stdout, stderr) => {
+					if (error === null) {
+						resolve({ stdout });
+						return;
+					}
+					reject(Object.assign(error, {
+						stdout,
+						stderr
+					}));
+				});
+			});
+			return parseJson(output);
+		} catch (error) {
+			const stderr = String(error.stderr ?? "");
+			if (missingIsEmpty && /\bE404\b/.test(stderr)) return null;
+			const redacted = redactUrls((stderr.split("\n").find((text) => /^npm (ERR!|error)/.test(text)) ?? error.message).replace(/^npm (ERR!|error) /, "").trim());
+			if (/\bEINTEGRITY\b/.test(stderr)) throw new NpmVmError("M-INTEGRITY", EXIT.verification, integrityMessage("the registry integrity", "other bytes", redacted));
+			throw this.#failure(redacted);
+		} finally {
+			rmSync(cwd, {
+				recursive: true,
+				force: true
+			});
+		}
+	}
+};
+/** Proxy settings as flags, since the env the transport sees carries none (spec DL-2). */
+function proxyFlags(config) {
+	const flags = [];
+	if (config.httpsProxy !== null) flags.push(`--https-proxy=${config.httpsProxy}`);
+	if (config.proxy !== null) flags.push(`--proxy=${config.proxy}`);
+	if (config.noproxy !== null) flags.push(`--noproxy=${config.noproxy}`);
+	return flags;
+}
+function parseJson(text) {
+	const trimmed = text.trim();
+	if (trimmed === "") return null;
+	return JSON.parse(trimmed);
+}
+function asList(value) {
+	return (Array.isArray(value) ? value : [value]).filter((item) => typeof item === "object" && item !== null);
+}
+function readString(record, key) {
+	const value = record[key];
+	return typeof value === "string" ? value : null;
+}
+function readObject(record, key) {
+	const value = record[key];
+	return typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
+}
+function isSignature(value) {
+	return typeof value === "object" && value !== null && typeof value.keyid === "string" && typeof value.sig === "string";
+}
+//#endregion
+//#region src/install/keys.ts
+const REGISTRY_KEYS = [{
+	keyid: "SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA",
+	key: "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE1Olb3zMAFFxXKHiIkQO5cJ3Yhl5i6UPp+IhuteBJbuHcA5UogKo0EWtlWwW6KSaKoTNEYL7JlCQiVnkhBktUgg==",
+	expires: "2025-01-29T00:00:00.000Z"
+}, {
+	keyid: "SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U",
+	key: "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEY6Ya7W++7aUPzvMTrezH6Ycx3c+HOKYCcNGybJZSCJq/fd7Qa8uuAKtdIkUQtQiEKERhAmE5lMMJhP8OkDOa2g==",
+	expires: null
+}];
+const EXTRA_KEYS_FILE = "keys.json";
+/**
+* Keys added beside the built-in ones from `<home>/state/keys.json`, for registries that sign with their own keys.
+* Anything able to write there could replace the runtime itself, so this adds no trust the home does not already hold.
+*/
+function loadKeyring(stateDir) {
+	let extra;
+	try {
+		extra = JSON.parse(readFileSync(join(stateDir, EXTRA_KEYS_FILE), "utf8"));
+	} catch {
+		return [...REGISTRY_KEYS];
+	}
+	const keys = Array.isArray(extra) ? extra : [];
+	return [...REGISTRY_KEYS, ...keys.filter((key) => typeof key === "object" && key !== null && typeof key.keyid === "string" && typeof key.key === "string" && (key.expires === null || typeof key.expires === "string"))];
+}
+//#endregion
+//#region src/install/index.ts
+function createContext(env = process.env, home, node = {
+	execPath: process.execPath,
+	version: process.version
+}) {
+	const dirs = resolveDirs(env, home);
+	return {
+		dirs,
+		own: findOwnNpm(node.execPath),
+		env,
+		nodeVersion: node.version,
+		nodePath: node.execPath,
+		keys: loadKeyring(dirs.state)
+	};
+}
+function toCandidate(version) {
+	return {
+		version: version.version,
+		enginesNode: version.enginesNode,
+		integrity: version.integrity,
+		entryPath: null,
+		signatures: version.signatures
+	};
+}
+/** Lazily loads the npm config and builds the transport once per process. */
+var TransportFactory = class {
+	#context;
+	#ready = null;
+	constructor(context) {
+		this.#context = context;
+	}
+	get() {
+		this.#ready ??= this.#create();
+		return this.#ready;
+	}
+	async #create() {
+		const { own, env, dirs } = this.#context;
+		const found = own?.version ?? null;
+		if (!transportUsable(own)) throw new NpmVmError("M-TRANSPORT", EXIT.transport, transportMessage(found, "too old or missing"));
+		const cwd = newWorkDir(dirs.tmp);
+		try {
+			const config = await loadNpmConfig(own, env, cwd, this.#context.nodePath);
+			return {
+				transport: new Transport(own, config, env, dirs.tmp, this.#context.nodePath),
+				config
+			};
+		} finally {
+			rmSync(cwd, {
+				recursive: true,
+				force: true
+			});
+		}
+	}
+};
+function createInstaller(context) {
+	const factory = new TransportFactory(context);
+	async function registryVersions(specs) {
+		const { transport } = await factory.get();
+		const byVersion = /* @__PURE__ */ new Map();
+		for (const spec of specs) for (const version of await transport.view(spec.exact ?? spec.range)) byVersion.set(version.version, version);
+		return [...byVersion.values()];
+	}
+	async function installTarball(selection, source, onPacked) {
+		const { candidate } = selection;
+		const owner = ownerRecord(context.dirs.machine.id);
+		if (source.published.version !== candidate.version || source.published.integrity !== candidate.integrity) throw new NpmVmError("M-INTEGRITY", EXIT.verification, integrityMessage(candidate.integrity, source.published.integrity, `the registry no longer serves npm ${candidate.version} with this integrity`));
+		const digests = await fileDigests(source.file);
+		checkIntegrity(digests, candidate.integrity, selection.hashes);
+		const keyid = await verifySignatures({
+			name: "npm",
+			version: candidate.version,
+			integrity: candidate.integrity,
+			signatures: source.published.signatures,
+			publishedAt: source.publishedAt,
+			keys: context.keys,
+			registry: source.registry,
+			pinned: selection.hashes.length > 0
+		});
+		if (onPacked !== void 0) await onPacked(source, digests);
+		const work = newWorkDir(stagingDir(context.dirs.cache));
+		try {
+			const extracted = join(work, "package");
+			mkdirSync(extracted, { mode: 448 });
+			await safeExtract(source.file, extracted);
+			checkExtracted(extracted, candidate, context.nodeVersion);
+			writeVerified(extracted, {
+				version: candidate.version,
+				integrity: candidate.integrity,
+				keyid,
+				sha256: digests.sha256hex,
+				sha224: digests.sha224hex,
+				verifiedAt: (/* @__PURE__ */ new Date()).toISOString()
+			});
+			const canonical = canonicalEntry(context.dirs.cache, candidate.version, candidate.integrity);
+			mkdirSync(join(canonical, ".."), {
+				recursive: true,
+				mode: 448
+			});
+			const published = publishEntry(extracted, canonical, candidate.integrity, owner);
+			touchUsed(published.entryPath);
+			return published;
+		} finally {
+			rmSync(work, {
+				recursive: true,
+				force: true
+			});
+		}
+	}
+	return {
+		nodeVersion: context.nodeVersion,
+		ownNpm: () => context.own,
+		cached: async () => listEntries(context.dirs.cache, context.keys),
+		registry: async (specs) => (await registryVersions(specs)).map(toCandidate),
+		entryPathFor: (candidate) => canonicalEntry(context.dirs.cache, candidate.version, candidate.integrity),
+		async registryIdentity() {
+			const { config } = await factory.get();
+			return createHash("sha256").update(config.registry).digest("hex").slice(0, 12);
+		},
+		installTarball: (selection, source) => installTarball(selection, source),
+		async ensure(selection, options = {}) {
+			const { candidate } = selection;
+			const owner = ownerRecord(context.dirs.machine.id);
+			if (candidate.entryPath !== null && validateEntry(candidate.entryPath, candidate.integrity)) {
+				const lease = await acquireShared(candidate.entryPath, owner);
+				if (lease !== null && validateEntry(candidate.entryPath, candidate.integrity)) {
+					touchUsed(candidate.entryPath);
+					return {
+						entryPath: candidate.entryPath,
+						lease
+					};
+				}
+				lease?.release();
+			}
+			if (options.offline ?? (context.env["NPM_VM_OFFLINE"] ?? "") !== "") throw new NpmVmError("M-NOMATCH", EXIT.resolution, `npm ${candidate.version} is not usable from the cache and NPM_VM_OFFLINE forbids the registry.`);
+			const { transport, config } = await factory.get();
+			const published = (await transport.view(candidate.version)).find((item) => item.version === candidate.version);
+			if (published === void 0) throw new NpmVmError("M-INTEGRITY", EXIT.verification, integrityMessage(candidate.integrity, "nothing", `the registry no longer serves npm ${candidate.version}`));
+			const work = newWorkDir(context.dirs.tmp);
+			try {
+				return await installTarball(selection, {
+					file: (await transport.pack(candidate.version, work)).file,
+					published,
+					publishedAt: async () => (await transport.times())[candidate.version] ?? null,
+					registry: config.registry
+				}, options.onPacked);
+			} finally {
+				rmSync(work, {
+					recursive: true,
+					force: true
+				});
+			}
+		}
+	};
+}
+/** The extracted manifest is authoritative for name, version and engines (spec SEC-5). */
+function checkExtracted(dir, candidate, nodeVersion) {
+	let pkg;
+	try {
+		pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+	} catch (error) {
+		throw new NpmVmError("M-INTEGRITY", EXIT.verification, integrityMessage("npm package.json", "unreadable", error.message));
+	}
+	if (pkg["name"] !== "npm" || pkg["version"] !== candidate.version) throw new NpmVmError("M-INTEGRITY", EXIT.verification, integrityMessage(`npm@${candidate.version}`, `${String(pkg["name"])}@${String(pkg["version"])}`, "the tarball holds a different package"));
+	const engines = pkg["engines"];
+	const node = typeof engines === "object" && engines !== null ? engines["node"] : void 0;
+	if (typeof node === "string" && !semver.satisfies(nodeVersion, node, { includePrerelease: true })) throw new NpmVmError("M-ENGINE", EXIT.resolution, engineMessage(candidate.version, node, nodeVersion));
+}
+//#endregion
+//#region src/project.ts
+const BOOLEANS = /* @__PURE__ */ new Set(["global", "workspaces"]);
+const SHORTHANDS = {
+	C: "prefix",
+	g: "global",
+	L: "location",
+	ws: "workspaces"
+};
+/**
+* The subset of nopt that decides the prefix: `--flag value`, `--flag=value`, `--no-flag`, `--flag true|false` for booleans, npm's shorthands and `--`.
+* Later flags win, as in nopt.
+*/
+function parsePrefixFlags(argv, cwd) {
+	const flags = {
+		prefix: null,
+		global: null,
+		location: null,
+		workspaces: null
+	};
+	for (let i = 0; i < argv.length; i += 1) {
+		const arg = argv[i];
+		if (arg === "--") break;
+		let name;
+		let value = null;
+		if (arg.startsWith("--")) {
+			const eq = arg.indexOf("=");
+			name = eq === -1 ? arg.slice(2) : arg.slice(2, eq);
+			value = eq === -1 ? null : arg.slice(eq + 1);
+			name = SHORTHANDS[name] ?? name;
+		} else if (arg.startsWith("-") && arg.length > 1 && SHORTHANDS[arg.slice(1)] !== void 0) name = SHORTHANDS[arg.slice(1)];
+		else continue;
+		let negated = false;
+		if (name.startsWith("no-") && BOOLEANS.has(name.slice(3))) {
+			negated = true;
+			name = name.slice(3);
+		}
+		if (BOOLEANS.has(name)) {
+			let bool = !negated;
+			if (value !== null) bool = value !== "false";
+			else if (!negated && (argv[i + 1] === "true" || argv[i + 1] === "false")) {
+				bool = argv[i + 1] === "true";
+				i += 1;
+			}
+			if (name === "global") flags.global = bool;
+			else flags.workspaces = bool;
+			continue;
+		}
+		if (name !== "prefix" && name !== "location") continue;
+		if (value === null) {
+			if (i + 1 >= argv.length) continue;
+			value = argv[i + 1];
+			i += 1;
+		}
+		if (name === "prefix") flags.prefix = resolve(cwd, value);
+		else flags.location = value;
+	}
+	return flags;
+}
+/** Global mode from the command line and the npm env, CLI winning (spec RES-3). */
+function isGlobalMode(flags, env) {
+	const fromEnv = env["npm_config_global"];
+	const global = flags.global ?? (fromEnv === void 0 || fromEnv === "" ? null : ![
+		"false",
+		"0",
+		"null"
+	].includes(fromEnv));
+	const location = flags.location ?? env["npm_config_location"] ?? null;
+	return global === true || location === "global";
+}
+function hasPackageJson(dir) {
+	try {
+		return statSync(join(dir, "package.json")).isFile();
+	} catch {
+		return false;
+	}
+}
+function hasNodeModules(dir) {
+	try {
+		return statSync(join(dir, "node_modules")).isDirectory();
+	} catch {
+		return false;
+	}
+}
+function* walkUp(start) {
+	let dir = resolve(start);
+	for (;;) {
+		yield dir;
+		const parent = dirname(dir);
+		if (parent === dir) return;
+		dir = parent;
+	}
+}
+/** The `workspaces` patterns of a manifest: the array form or `{ packages: [] }`, else none. */
+function workspacePatterns(pkg) {
+	if (typeof pkg !== "object" || pkg === null) return [];
+	let raw = pkg.workspaces;
+	if (typeof raw === "object" && raw !== null && !Array.isArray(raw)) raw = raw.packages;
+	if (!Array.isArray(raw)) return [];
+	return raw.filter((entry) => typeof entry === "string");
+}
+/**
+* Whether `candidate` is one of the workspaces `root` declares, matched like `@npmcli/map-workspaces`.
+* A pattern selects directories holding a `package.json`, `!pattern` removes matches, and `node_modules` never matches.
+*/
+function isWorkspaceOf(root, candidate, patterns) {
+	const rel = relative(root, candidate);
+	if (rel === "" || rel.startsWith("..") || isAbsolute(rel) || !hasPackageJson(candidate)) return false;
+	if (rel.split(sep).includes("node_modules")) return false;
+	const posix = rel.split(sep).join("/");
+	const { positive, negative } = splitPatterns(patterns);
+	return positive.some((pattern) => matchesGlob(posix, pattern)) && !negative.some((pattern) => matchesGlob(posix, pattern));
+}
+function splitPatterns(patterns) {
+	const positive = [];
+	const negative = [];
+	for (const raw of patterns) {
+		const bangs = /^!+/.exec(raw)?.[0].length ?? 0;
+		const pattern = normalizePattern(raw.slice(bangs));
+		if (bangs % 2 === 1) {
+			negative.push(pattern);
+			continue;
+		}
+		for (let i = negative.length - 1; i >= 0; i -= 1) if (matchesGlob(pattern, negative[i])) negative.splice(i, 1);
+		positive.push(pattern);
+	}
+	return {
+		positive,
+		negative
+	};
+}
+function normalizePattern(pattern) {
+	return pattern.replace(/\\/g, "/").replace(/^\.?\/+/, "").replace(/\/+$/, "");
+}
+function readManifest(dir) {
+	try {
+		return JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+	} catch {
+		return null;
+	}
+}
+/**
+* Mirrors `@npmcli/config` `loadLocalPrefix` (spec RES-2): a CLI prefix is final.
+* Otherwise the nearest ancestor with `package.json` or `node_modules` wins, promoted to a parent whose `workspaces` include it unless `--no-workspaces` or global mode.
+*/
+function findProject(argv, cwd, env = process.env) {
+	const flags = parsePrefixFlags(argv, cwd);
+	const global = isGlobalMode(flags, env);
+	if (flags.prefix !== null) return {
+		root: flags.prefix,
+		global,
+		cliPrefix: flags.prefix
+	};
+	let localPrefix = null;
+	for (const dir of walkUp(cwd)) {
+		const manifest = hasPackageJson(dir);
+		if (localPrefix === null) {
+			if (manifest || hasNodeModules(dir)) {
+				localPrefix = dir;
+				if (flags.workspaces === false || global) break;
+			}
+			continue;
+		}
+		if (!manifest) continue;
+		const pkg = readManifest(dir);
+		if (pkg !== null && isWorkspaceOf(dir, localPrefix, workspacePatterns(pkg))) {
+			localPrefix = dir;
+			break;
+		}
+	}
+	return {
+		root: localPrefix ?? resolve(cwd),
+		global,
+		cliPrefix: null
+	};
+}
+//#endregion
+//#region src/index.ts
+/** Resolves the npm to run for `argv` in `cwd` (spec section 5); writes only under the cache, spawns npm only as the transport. */
+function resolveNpm(argv, cwd, options = {}) {
+	return resolveNpmWith(argv, cwd, options, createInstaller(createContext(options.env ?? process.env, options.home)));
+}
+async function resolveNpmWith(argv, cwd, options, providers) {
+	const env = options.env ?? process.env;
+	const own = providers.ownNpm();
+	const ownResult = (projectRoot, source, warning) => {
+		if (own === null) throw new NpmVmError("M-TRANSPORT", EXIT.transport, "No npm found beside the active Node; reinstall Node.");
+		return {
+			kind: "own",
+			version: own.version,
+			cliPath: own.cliPath,
+			source,
+			projectRoot,
+			selection: null,
+			specs: null,
+			warning
+		};
+	};
+	if (nonEmpty(env["NPM_VM_DISABLE"])) return ownResult(null, null, null);
+	const project = findProject(argv, cwd, env);
+	if (project.global) return ownResult(project.root, null, null);
+	let parsed;
+	let source;
+	if (nonEmpty(env["NPM_VM_VERSION"])) {
+		parsed = {
+			specs: [parseVersionSpec(env["NPM_VM_VERSION"], "NPM_VM_VERSION")],
+			onFail: "error",
+			field: "devEngines"
+		};
+		source = {
+			file: "NPM_VM_VERSION",
+			field: "env"
+		};
+	} else {
+		const file = join(project.root, "package.json");
+		let read;
+		try {
+			read = readSpecs(file);
+		} catch (error) {
+			if (!(error instanceof SpecError)) throw error;
+			const message = `${file}: ${error.message}`;
+			const failure = new NpmVmError("M-NOMATCH", EXIT.resolution, message);
+			return applyPolicy(error.onFail, failure, () => ownResult(project.root, null, message));
+		}
+		if (read === null) return ownResult(project.root, null, null);
+		parsed = read;
+		source = {
+			file,
+			field: read.field
+		};
+	}
+	if (own !== null && ownNpmSatisfies(own.version, parsed.specs)) return ownResult(project.root, source, null);
+	const cached = await providers.cached(parsed.specs);
+	let result = selectCandidate(parsed.specs, cached, providers.nodeVersion);
+	if (result.kind === "failed" && !options.offline && !nonEmpty(env["NPM_VM_OFFLINE"])) {
+		let fromRegistry;
+		try {
+			fromRegistry = await providers.registry(parsed.specs);
+		} catch (error) {
+			if (!(error instanceof NpmVmError) || error.id !== "M-TRANSPORT") throw error;
+			return applyPolicy(parsed.onFail, error, () => ownResult(project.root, source, error.message));
+		}
+		result = selectCandidate(parsed.specs, fromRegistry, providers.nodeVersion);
+	}
+	if (result.kind === "selected") {
+		const { candidate } = result.selection;
+		const entry = candidate.entryPath ?? providers.entryPathFor(candidate);
+		return {
+			kind: candidate.entryPath === null ? "download" : "cached",
+			version: candidate.version,
+			cliPath: join(entry, "bin", "npm-cli.js"),
+			source,
+			projectRoot: project.root,
+			selection: result.selection,
+			specs: parsed.specs,
+			warning: null
+		};
+	}
+	const message = result.failure.kind === "engine" ? engineMessage(result.failure.version, result.failure.enginesNode, providers.nodeVersion) : noMatchMessage(parsed.specs, source.file, result.failure.reason);
+	const failure = new NpmVmError(result.failure.kind === "engine" ? "M-ENGINE" : "M-NOMATCH", EXIT.resolution, message);
+	return applyPolicy(parsed.onFail, failure, () => ownResult(project.root, source, message));
+}
+/** `onFail` makes a failed resolution fatal, a warning before Node's own npm, or silent (spec RES-7). */
+function applyPolicy(onFail, failure, fallback) {
+	if (onFail === "ignore") return {
+		...fallback(),
+		warning: null
+	};
+	if (onFail === "warn") return fallback();
+	throw failure;
+}
+/** Reads and validates the project's specs; a broken file or range follows its own `onFail` when readable, else errors. */
+function readSpecs(file) {
+	let text;
+	try {
+		text = readFileSync(file, "utf8");
+	} catch {
+		return null;
+	}
+	let pkg;
+	try {
+		pkg = JSON.parse(text);
+	} catch (error) {
+		throw new NpmVmError("M-NOMATCH", EXIT.resolution, `${file} is not valid JSON: ${error.message}`);
+	}
+	return parseSpecs(pkg);
+}
+function nonEmpty(value) {
+	return value !== void 0 && value !== "";
+}
+//#endregion
+export { newToken as A, lockedMessage as B, verifySignatures as C, parseSpecs as D, SpecError as E, shellBinary as F, EXIT as G, redactUrls as H, findOwnNpm as I, NpmVmError as K, abiMessage as L, ownerRecord as M, isLive as N, parseVersionSpec as O, powershellPath as P, changedMessage as R, safeExtract as S, sriHex as T, restartMessage as U, provenanceMessage as V, transportMessage as W, withSharingRetry as _, createInstaller as a, fileDigests as b, newWorkDir as c, resolveDirs as d, lastUsed as f, removeWithRetry as g, atomicWrite as h, createContext as i, ownerLive as j, listLeases as k, transportUsable as l, atomicRename as m, resolveNpmWith as n, loadKeyring as o, pruneCache as p, isNpmVmError as q, findProject as r, Transport as s, resolveNpm as t, loadNpmConfig as u, listEntries as v, selectCandidate as w, readVerified as x, stagingDir as y, dirPermsMessage as z };
+
+//# sourceMappingURL=src-NhNG2mnQ.js.map