@pnpm/engine.pm.commands 1101.1.20 → 1101.1.21

package/lib/index.d.ts

@@ -1,4 +1,5 @@
 export { selfUpdate } from './self-updater/index.js';
 export { exePlatformPkgDirName, exePlatformPkgDirNameNext, installPnpm, installPnpmToStore, linkExePlatformBinary } from './self-updater/installPnpm.js';
+export { verifyPnpmEngineIdentity, type VerifyPnpmEngineIdentityOptions } from './self-updater/verifyPnpmEngineIdentity.js';
 export { setup } from './setup/index.js';
 export { withCmd } from './with/index.js';

package/lib/index.js

@@ -1,5 +1,6 @@
 export { selfUpdate } from './self-updater/index.js';
 export { exePlatformPkgDirName, exePlatformPkgDirNameNext, installPnpm, installPnpmToStore, linkExePlatformBinary } from './self-updater/installPnpm.js';
+export { verifyPnpmEngineIdentity } from './self-updater/verifyPnpmEngineIdentity.js';
 export { setup } from './setup/index.js';
 export { withCmd } from './with/index.js';
 //# sourceMappingURL=index.js.map

package/lib/self-updater/installPnpm.d.ts

@@ -2,6 +2,7 @@ import { type GlobalAddOptions } from '@pnpm/global.commands';
 import type { EnvLockfile } from '@pnpm/lockfile.types';
 import { type StoreController } from '@pnpm/store.controller';
 import type { Registries } from '@pnpm/types';
+import { type VerifyPnpmEngineIdentityOptions } from './verifyPnpmEngineIdentity.js';
 export interface InstallPnpmResult {
     binDir: string;
     baseDir: string;
@@ -15,6 +16,8 @@ export interface InstallPnpmOptions extends GlobalAddOptions {
         name: string;
         version: string;
     };
+    /** See {@link VerifyPnpmEngineIdentityOptions.trustedKeys} — a test seam. */
+    trustedKeys?: VerifyPnpmEngineIdentityOptions['trustedKeys'];
 }
 /**
  * Installs pnpm to the global packages directory (for self-update).
@@ -36,7 +39,7 @@ export declare function installPnpmToStore(pnpmVersion: string, opts: {
         name: string;
         version: string;
     };
-}): Promise<{
+} & VerifyPnpmEngineIdentityOptions): Promise<{
     binDir: string;
 }>;
 /**

package/lib/self-updater/installPnpm.js

@@ -11,6 +11,7 @@ import { headlessInstall } from '@pnpm/installing.deps-restorer';
 import { registerProject } from '@pnpm/store.controller';
 import { familySync } from 'detect-libc';
 import { symlinkDir } from 'symlink-dir';
+import { verifyPnpmEngineIdentity } from './verifyPnpmEngineIdentity.js';
 // @pnpm/exe has platform-specific binaries, so its GVS hash must
 // include ENGINE_NAME for correct per-platform resolution.
 const PNPM_ALLOW_BUILDS = { '@pnpm/exe': true };
@@ -50,6 +51,9 @@ export async function installPnpmToStore(pnpmVersion, opts) {
         }
         return { binDir };
     }
+    // Reached only on a store cache miss (a genuine download), so verifying the
+    // pnpm engine's registry signature here does not slow down repeated commands.
+    await verifyPnpmEngineIdentity(opts.envLockfile, pnpmVersion, opts);
     // Install to a temporary directory — headless install with GVS enabled
     // will populate the global virtual store
     const tmpInstallDir = path.join(opts.storeDir, '.tmp', `pnpm-${pnpmVersion}-${Date.now()}`);
@@ -116,6 +120,11 @@ async function installPnpmToGlobalDir(opts, pkgName, version, wantedLockfile) {
     const binDir = path.join(installDir, 'bin');
     try {
         if (wantedLockfile != null && opts.storeController != null && opts.storeDir != null) {
+            if (opts.envLockfile != null) {
+                // Reached only when actually downloading (no matching global install),
+                // so the signature check does not run on every invocation.
+                await verifyPnpmEngineIdentity(opts.envLockfile, version, opts);
+            }
             await installFromLockfile(installDir, binDir, {
                 wantedLockfile,
                 allowBuilds: PNPM_ALLOW_BUILDS,

package/lib/self-updater/selfUpdate.js

@@ -3,7 +3,7 @@ import path from 'node:path';
 import { linkBins } from '@pnpm/bins.linker';
 import { isExecutedByCorepack, packageManager } from '@pnpm/cli.meta';
 import { docsUrl } from '@pnpm/cli.utils';
-import { parsePackageManager, types as allTypes } from '@pnpm/config.reader';
+import { parsePackageManager, shouldPersistLockfile, types as allTypes } from '@pnpm/config.reader';
 import { getPublishedByPolicy } from '@pnpm/config.version-policy';
 import { PnpmError } from '@pnpm/error';
 import { createResolver, makeResolutionStrict } from '@pnpm/installing.client';
@@ -156,13 +156,15 @@ export async function handler(opts, params) {
                 }
                 if (manifestChanged)
                     await writeProjectManifest(manifest);
-                const store = await createStoreController(opts);
-                await resolvePackageManagerIntegrities(resolution.manifest.version, {
-                    registries: opts.registries,
-                    rootDir: opts.rootProjectManifestDir,
-                    storeController: store.ctrl,
-                    storeDir: store.dir,
-                });
+                if (shouldPersistLockfile({ ...opts.wantedPackageManager, fromDevEngines: true })) {
+                    const store = await createStoreController(opts);
+                    await resolvePackageManagerIntegrities(resolution.manifest.version, {
+                        registries: opts.registries,
+                        rootDir: opts.rootProjectManifestDir,
+                        storeController: store.ctrl,
+                        storeDir: store.dir,
+                    });
+                }
             }
             else {
                 manifest.packageManager = `pnpm@${resolution.manifest.version}`;

package/lib/self-updater/verifyPnpmEngineIdentity.d.ts

@@ -0,0 +1,40 @@
+import { type RegistryKey, type VerifySignaturesOptions } from '@pnpm/deps.security.signatures';
+import type { EnvLockfile } from '@pnpm/lockfile.types';
+import type { Registries, RegistryConfig } from '@pnpm/types';
+export type VerifyPnpmEngineIdentityOptions = VerifySignaturesOptions & {
+    registries: Registries;
+    configByUri?: Record<string, RegistryConfig>;
+    /**
+     * The npm signing keys to trust. Defaults to {@link getNpmSigningKeys} (npm's
+     * embedded public keys). A test seam only — passing an empty array skips
+     * verification. Not reachable from project config, so it cannot be used to
+     * weaken verification for a real install.
+     */
+    trustedKeys?: RegistryKey[];
+};
+/**
+ * Verifies that the pnpm engine about to be installed (and then executed) for an
+ * automatic version switch or self-update is genuinely the published `pnpm` —
+ * i.e. the bytes recorded in the env lockfile carry a valid npm registry
+ * signature for their exact `name@version`.
+ *
+ * The wanted pnpm version comes from a repository's `packageManager` /
+ * `devEngines.packageManager` field, and the project controls the lockfile
+ * integrity and the registry the bytes are fetched from — so without this
+ * check, a cloned repository could make pnpm download and run an arbitrary
+ * native binary. Signatures are verified against npm's embedded public keys
+ * (see `getNpmSigningKeys`), so a project-controlled registry cannot answer with
+ * its own key pair; the signed packument is fetched from the configured registry,
+ * which an npm mirror proxies transparently.
+ *
+ * Throws when verification detects tampering (an invalid signature), when a
+ * package/version is absent from the registry, or when an engine component
+ * present in the lockfile carries no integrity metadata — pnpm can install a
+ * tarball without integrity, so a missing integrity must fail closed rather
+ * than silently exempt that component from verification. Even an unreachable
+ * registry fails closed (with `PNPM_ENGINE_IDENTITY_UNVERIFIABLE`): the
+ * lockfile integrity is project-controlled, so it is not a safe fallback.
+ * This runs only when the engine is actually being installed (a store cache
+ * miss), so it does not add a network round trip to every command.
+ */
+export declare function verifyPnpmEngineIdentity(envLockfile: EnvLockfile, pnpmVersion: string, opts: VerifyPnpmEngineIdentityOptions): Promise<void>;

package/lib/self-updater/verifyPnpmEngineIdentity.js

@@ -0,0 +1,102 @@
+import { pickRegistryForPackage } from '@pnpm/config.pick-registry-for-package';
+import { getNpmSigningKeys, verifyInstalledPackageSignatures, } from '@pnpm/deps.security.signatures';
+import { PnpmError } from '@pnpm/error';
+import { createGetAuthHeaderByURI } from '@pnpm/network.auth-header';
+import { familySync } from 'detect-libc';
+import { exePlatformPkgDirName, exePlatformPkgDirNameNext } from './installPnpm.js';
+/**
+ * Verifies that the pnpm engine about to be installed (and then executed) for an
+ * automatic version switch or self-update is genuinely the published `pnpm` —
+ * i.e. the bytes recorded in the env lockfile carry a valid npm registry
+ * signature for their exact `name@version`.
+ *
+ * The wanted pnpm version comes from a repository's `packageManager` /
+ * `devEngines.packageManager` field, and the project controls the lockfile
+ * integrity and the registry the bytes are fetched from — so without this
+ * check, a cloned repository could make pnpm download and run an arbitrary
+ * native binary. Signatures are verified against npm's embedded public keys
+ * (see `getNpmSigningKeys`), so a project-controlled registry cannot answer with
+ * its own key pair; the signed packument is fetched from the configured registry,
+ * which an npm mirror proxies transparently.
+ *
+ * Throws when verification detects tampering (an invalid signature), when a
+ * package/version is absent from the registry, or when an engine component
+ * present in the lockfile carries no integrity metadata — pnpm can install a
+ * tarball without integrity, so a missing integrity must fail closed rather
+ * than silently exempt that component from verification. Even an unreachable
+ * registry fails closed (with `PNPM_ENGINE_IDENTITY_UNVERIFIABLE`): the
+ * lockfile integrity is project-controlled, so it is not a safe fallback.
+ * This runs only when the engine is actually being installed (a store cache
+ * miss), so it does not add a network round trip to every command.
+ */
+export async function verifyPnpmEngineIdentity(envLockfile, pnpmVersion, opts) {
+    const trustedKeys = opts.trustedKeys ?? getNpmSigningKeys();
+    if (trustedKeys.length === 0)
+        return; // test seam: no trusted keys means skip
+    const toVerify = collectEnginePackagesToVerify(envLockfile, opts.registries);
+    if (toVerify.length === 0) {
+        throw new PnpmError('PNPM_ENGINE_IDENTITY_UNVERIFIABLE', `Cannot verify the identity of pnpm@${pnpmVersion}: its integrity metadata is missing from pnpm-lock.yaml.`);
+    }
+    const getAuthHeader = createGetAuthHeaderByURI(opts.configByUri ?? {});
+    let result;
+    try {
+        result = await verifyInstalledPackageSignatures(toVerify, trustedKeys, getAuthHeader, opts);
+    }
+    catch (err) {
+        // Fail closed: we will not run a downloaded pnpm we could not verify, even
+        // when the failure is "could not reach the registry". The lockfile integrity
+        // is project-controlled, so it is not a safe fallback.
+        throw new PnpmError('PNPM_ENGINE_IDENTITY_UNVERIFIABLE', `Refusing to run pnpm@${pnpmVersion}: its npm registry signature could not be verified (${String(err)}).`, { hint: 'The registry signing keys / packument must be reachable to verify the pnpm release. Set `pmOnFail` to `ignore` to skip the version switch.' });
+    }
+    if (result.verified)
+        return;
+    const onlyUnreachable = result.failures.every((f) => f.category === 'unreachable');
+    throw new PnpmError(onlyUnreachable ? 'PNPM_ENGINE_IDENTITY_UNVERIFIABLE' : 'PNPM_ENGINE_IDENTITY_MISMATCH', `Refusing to run pnpm@${pnpmVersion}: its npm registry signature could not be verified ` +
+        `(${describe(result.failures)}). The bytes selected by this project's lockfile/registry do not match a published, signed pnpm release.`, { hint: 'This can indicate a tampered lockfile or a malicious/unreachable registry. Set `pmOnFail` to `ignore` to skip the version switch if this is unexpected.' });
+}
+function collectEnginePackagesToVerify(envLockfile, registries) {
+    const pmDeps = envLockfile.importers['.']?.packageManagerDependencies ?? {};
+    const toVerify = [];
+    for (const name of ['pnpm', '@pnpm/exe']) {
+        const version = pmDeps[name]?.version;
+        if (version == null)
+            continue;
+        toVerify.push(engineComponentToVerify(envLockfile, registries, { name, version }));
+    }
+    // The bytes actually executed are the host's `@pnpm/exe` platform binary,
+    // listed as an optional dependency of `@pnpm/exe`.
+    const exeVersion = pmDeps['@pnpm/exe']?.version;
+    if (exeVersion != null) {
+        const optionalDeps = envLockfile.snapshots[`@pnpm/exe@${exeVersion}`]?.optionalDependencies ?? {};
+        const libcFamily = familySync();
+        const candidateNames = [
+            `@pnpm/${exePlatformPkgDirName(process.platform, process.arch, libcFamily)}`,
+            `@pnpm/${exePlatformPkgDirNameNext(process.platform, process.arch, libcFamily)}`,
+        ];
+        for (const platformName of candidateNames) {
+            const platformVersion = optionalDeps[platformName];
+            if (platformVersion == null)
+                continue;
+            // The first candidate present in the lockfile is the binary the install
+            // will link and execute, so it is the one that must be verifiable.
+            toVerify.push(engineComponentToVerify(envLockfile, registries, { name: platformName, version: platformVersion }));
+            break;
+        }
+    }
+    return toVerify;
+}
+function engineComponentToVerify(envLockfile, registries, { name, version }) {
+    const integrity = registryIntegrity(envLockfile.packages[`${name}@${version}`]?.resolution);
+    if (integrity == null) {
+        throw new PnpmError('PNPM_ENGINE_IDENTITY_UNVERIFIABLE', `Cannot verify the identity of ${name}@${version}: its integrity metadata is missing from pnpm-lock.yaml.`);
+    }
+    return { name, version, registry: pickRegistryForPackage(registries, name), integrity };
+}
+function registryIntegrity(resolution) {
+    const integrity = resolution?.integrity;
+    return typeof integrity === 'string' && integrity ? integrity : undefined;
+}
+function describe(failures) {
+    return failures.map(({ name, version, reason }) => `${name}@${version}: ${reason}`).join('; ');
+}
+//# sourceMappingURL=verifyPnpmEngineIdentity.js.map

package/lib/with/with.js

@@ -64,6 +64,19 @@ export async function handler(opts, params) {
             registries: opts.registries,
             virtualStoreDirMaxLength: opts.virtualStoreDirMaxLength,
             packageManager: { name: packageManager.name, version: packageManager.version },
+            // Network settings so the engine identity check can reach the canonical
+            // npm registry through the user's proxy / TLS configuration.
+            ca: opts.ca,
+            cert: opts.cert,
+            key: opts.key,
+            httpProxy: opts.httpProxy,
+            httpsProxy: opts.httpsProxy,
+            noProxy: opts.noProxy,
+            strictSsl: opts.strictSsl,
+            localAddress: opts.localAddress,
+            maxSockets: opts.maxSockets,
+            configByUri: opts.configByUri,
+            timeout: opts.fetchTimeout,
         }));
     }
     finally {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pnpm/engine.pm.commands",
-  "version": "1101.1.20",
+  "version": "1101.1.21",
   "description": "pnpm commands for self-updating and setting up pnpm",
   "keywords": [
     "pnpm",
@@ -35,27 +35,30 @@
     "render-help": "^2.0.0",
     "semver": "^7.8.1",
     "symlink-dir": "^10.0.1",
-    "@pnpm/bins.linker": "1100.0.11",
-    "@pnpm/building.policy": "1100.0.8",
-    "@pnpm/cli.meta": "1100.0.6",
-    "@pnpm/cli.utils": "1101.0.9",
-    "@pnpm/config.reader": "1101.6.0",
-    "@pnpm/deps.graph-hasher": "1100.2.3",
+    "@pnpm/bins.linker": "1100.0.12",
+    "@pnpm/cli.meta": "1100.0.7",
+    "@pnpm/cli.utils": "1101.0.10",
+    "@pnpm/config.pick-registry-for-package": "1100.0.8",
+    "@pnpm/building.policy": "1100.0.9",
+    "@pnpm/deps.graph-hasher": "1100.2.4",
+    "@pnpm/config.version-policy": "1100.1.4",
+    "@pnpm/deps.security.signatures": "1101.2.0",
+    "@pnpm/config.reader": "1101.7.0",
     "@pnpm/error": "1100.0.0",
-    "@pnpm/global.packages": "1100.0.6",
-    "@pnpm/installing.client": "1100.2.5",
-    "@pnpm/installing.deps-restorer": "1101.1.9",
-    "@pnpm/global.commands": "1100.0.25",
-    "@pnpm/installing.env-installer": "1101.1.6",
-    "@pnpm/lockfile.types": "1100.0.9",
-    "@pnpm/resolving.npm-resolver": "1101.5.0",
-    "@pnpm/store.connection-manager": "1100.2.6",
-    "@pnpm/types": "1101.3.0",
+    "@pnpm/global.packages": "1100.0.7",
+    "@pnpm/installing.env-installer": "1101.1.7",
+    "@pnpm/lockfile.fs": "1100.1.4",
+    "@pnpm/installing.client": "1100.2.6",
+    "@pnpm/lockfile.types": "1100.0.10",
+    "@pnpm/network.auth-header": "1101.1.1",
+    "@pnpm/store.connection-manager": "1100.2.7",
+    "@pnpm/types": "1101.3.1",
     "@pnpm/shell.path": "1100.0.1",
-    "@pnpm/config.version-policy": "1100.1.3",
-    "@pnpm/lockfile.fs": "1100.1.3",
-    "@pnpm/workspace.project-manifest-reader": "1100.0.10",
-    "@pnpm/store.controller": "1101.0.11"
+    "@pnpm/global.commands": "1100.0.26",
+    "@pnpm/workspace.project-manifest-reader": "1100.0.11",
+    "@pnpm/store.controller": "1101.0.12",
+    "@pnpm/installing.deps-restorer": "1101.1.10",
+    "@pnpm/resolving.npm-resolver": "1101.5.1"
   },
   "peerDependencies": {
     "@pnpm/logger": "^1001.0.1"
@@ -65,12 +68,12 @@
     "@types/cross-spawn": "^6.0.6",
     "@types/ramda": "0.31.1",
     "@types/semver": "7.7.1",
-    "@pnpm/constants": "1100.0.0",
+    "@pnpm/engine.pm.commands": "1101.1.21",
     "@pnpm/error": "1100.0.0",
+    "@pnpm/testing.mock-agent": "1101.0.1",
     "@pnpm/logger": "1100.0.0",
-    "@pnpm/prepare": "1100.0.13",
-    "@pnpm/engine.pm.commands": "1101.1.20",
-    "@pnpm/testing.mock-agent": "1101.0.0"
+    "@pnpm/prepare": "1100.0.14",
+    "@pnpm/constants": "1100.0.0"
   },
   "engines": {
     "node": ">=22.13"