fix: enforce minimumReleaseAge on existing lockfile entries (#11583)

Closes #10438.

## What

Re-verify every entry in `pnpm-lock.yaml` against the policies the resolver chain was configured with — today: `minimumReleaseAge` in strict mode — right after the lockfile is loaded from disk and before any tarball is fetched. A locked version that fails the policy aborts the install with `ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION`; `minimumReleaseAgeExclude` is honored.

## Why

The policy only fires while pnpm is *choosing* a version. Once a version is pinned in the lockfile — e.g. a developer disabled the policy locally and committed a fresh dependency, or a CI cache restored a stale lockfile — every later `pnpm install` (including `--frozen-lockfile` and `pnpm fetch`) installs it without re-checking, which defeats the supply-chain protection the setting is supposed to provide.

The threat model is **a lockfile someone else resolved**, not local resolution: local resolution is already covered by the resolver's own per-version filter. bun fixed the same shape of bug in [oven-sh/bun#30526](oven-sh/bun#30526); this PR is the pnpm side.

## How

The fix introduces a generic `ResolutionVerifier` abstraction in the resolver chain — each resolver factory can ship a sibling verifier factory, exactly the way each resolver ships a `resolve` function. Today there's one verifier (npm); the shape leaves room for future ones (jsr, attestation-based, etc.) without changing the install-side interface.

- **`@pnpm/resolving.resolver-base`** exports the `ResolutionVerifier` / `ResolutionVerification` types — the shared contract.
- **`@pnpm/resolving.npm-resolver`** exports `createNpmResolutionVerifier`. Returns `undefined` when no policy is active, so callers can cheaply decide whether to iterate at all. When active, it inspects each lockfile entry, handles `minimumReleaseAgeExclude`, routes through named-registry prefixes (built-ins like `gh:` merged in), and uses `fetchFullMetadataCached` to fetch full registry metadata — decoupled from the resolver pipeline so neither `peekManifestFromStore` nor abbreviated metadata can hide the publish timestamp.
- **`@pnpm/resolving.default-resolver`** exports `createResolutionVerifier`, a combinator that asks each underlying verifier (today: npm) if it has work and returns `undefined` when none does. Designed so that adding more verifiers later doesn't change the install side.
- **`@pnpm/installing.client`** exposes `verifyResolution` on `Client`, built from the same `fetchFromRegistry` / `getAuthHeader` the resolver chain already uses — **no second fetcher is constructed**.
- **`@pnpm/store.connection-manager`** and **`@pnpm/testing.temp-store`** surface `verifyResolution` alongside the store controller they hand back, so it reaches `mutateModules` through the existing plumbing.
- **`@pnpm/installing.deps-installer`** gains one option on `StrictInstallOptions`: `verifyResolution?: ResolutionVerifier`. `mutateModules` invokes `verifyLockfileResolutions(ctx.wantedLockfile, opts.verifyResolution)` **once**, right after `getContext` returns the on-disk lockfile and before any path branches. When the verifier is `undefined`, the call is a no-op. The iteration is policy-neutral: dedupes by `(name, version)`, applies `pLimit(16)`, sorts violations stably, caps the printed list at 20 with an `…and N more` summary, throws a `PnpmError` carrying the verifier-supplied error code.

The error includes a recovery hint that points at `pnpm clean --lockfile` followed by `pnpm install` — the safe way to throw away a poisoned lockfile and rebuild from fresh resolution.

## Tests

- **9 unit tests** for `verifyLockfileResolutions` against a mock `ResolutionVerifier` — dedup, aggregation, stable ordering, the 20-entry cap, no-op behavior, the verifier-supplied error code surfacing in `PnpmError`.
- **13 integration tests** in `installing/deps-installer/test/install/minimumReleaseAge.ts` via the real `install()` entry — `testDefaults()` wires `verifyResolution` from `createTempStore` → `createClient`, so the npm verifier runs end-to-end at the install boundary. Covers the rejection scenario, `minimumReleaseAgeExclude`, the strict-mode toggle, the existing `minimumReleaseAge` resolver-side suite, and a `pnpm add` scenario where a pre-existing entry would otherwise survive resolution.
- **3 e2e tests** in `pnpm/test/install/minimumReleaseAge.ts` against the bundled CLI: rejection path with the right `ERR_PNPM_*` code and `pnpm clean --lockfile` hint in output, `minimumReleaseAgeExclude` honored, and the strict-off path (which now requires an explicit `minimumReleaseAgeStrict: false` since the config reader auto-enables strict mode when `minimumReleaseAge` is set).
- Existing `frozenLockfile` suite (12 tests) and npm-resolver suite (179 tests) still pass.

---------

Co-authored-by: Zoltan Kochan <z@kochan.io>

Author: ryo-manba

.changeset/cache-aware-minimum-release-age-gate.md

@@ -0,0 +1,12 @@
+---
+"@pnpm/resolving.resolver-base": minor
+"@pnpm/resolving.npm-resolver": minor
+"@pnpm/resolving.default-resolver": minor
+"@pnpm/installing.client": minor
+"@pnpm/store.connection-manager": minor
+"@pnpm/testing.temp-store": minor
+"@pnpm/installing.deps-installer": minor
+"pnpm": patch
+---
+
+Restructured the `minimumReleaseAge` lockfile revalidation gate around a generic `ResolutionVerifier` interface. Each resolver may now export a sibling verifier factory (today: `createNpmResolutionVerifier`) that re-checks an already-resolved lockfile entry against its policies; `createResolver`'s companion `createResolutionVerifier` combines them and the `Client` exposes the combined `verifyResolution` for the install layer to consume. The npm verifier reuses the same on-disk metadata mirror the resolver writes to, so steady-state installs pay only a headers-only conditional GET per locked package [#11675](https://github.com/pnpm/pnpm/issues/11675).

.changeset/revalidate-minimum-release-age.md

@@ -0,0 +1,6 @@
+---
+"@pnpm/installing.deps-installer": minor
+"pnpm": patch
+---
+
+`minimumReleaseAge` is now re-checked against `pnpm-lock.yaml` before any tarball is installed, so a freshly-published version pinned in the lockfile (e.g. by a developer who bypassed the policy locally) is no longer installed silently by other consumers or CI. Violating entries abort the install with `ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION`; `minimumReleaseAgeExclude` is honored. [#10438](https://github.com/pnpm/pnpm/issues/10438).

installing/client/src/index.ts

@@ -9,14 +9,17 @@ import type { CustomFetcher, CustomResolver } from '@pnpm/hooks.types'
 import { createGetAuthHeaderByURI } from '@pnpm/network.auth-header'
 import { createFetchFromRegistry, type DispatcherOptions } from '@pnpm/network.fetch'
 import {
+  createResolutionVerifier,
   createResolver as _createResolver,
+  type ResolutionVerifierFactoryOptions,
   type ResolveFunction,
   type ResolverFactoryOptions,
 } from '@pnpm/resolving.default-resolver'
+import type { ResolutionVerifier } from '@pnpm/resolving.resolver-base'
 import type { StoreIndex } from '@pnpm/store.index'
 import type { RegistryConfig } from '@pnpm/types'
 
-export type { ResolveFunction }
+export type { ResolutionVerifier, ResolveFunction }
 
 export type ClientOptions = {
   configByUri: Record<string, RegistryConfig>
@@ -35,22 +38,32 @@ export type ClientOptions = {
   preserveAbsolutePaths?: boolean
   fetchMinSpeedKiBps?: number
 } & ResolverFactoryOptions & DispatcherOptions
+  & Pick<ResolutionVerifierFactoryOptions, 'minimumReleaseAge' | 'minimumReleaseAgeStrict' | 'minimumReleaseAgeExclude'>
 
 export interface Client {
   fetchers: Fetchers
   resolve: ResolveFunction
   clearResolutionCache: () => void
+  /**
+   * Combined verifier across the resolver chain. `undefined` when no
+   * resolver-level policy is active (today: minimumReleaseAge strict mode).
+   * Used by the install layer to re-validate an already-resolved lockfile
+   * entry without re-doing resolution.
+   */
+  verifyResolution?: ResolutionVerifier
 }
 
 export function createClient (opts: ClientOptions): Client {
   const fetchFromRegistry = createFetchFromRegistry(opts)
   const getAuthHeader = createGetAuthHeaderByURI(opts.configByUri, opts.registries?.default)
 
   const { resolve, clearCache: clearResolutionCache } = _createResolver(fetchFromRegistry, getAuthHeader, { ...opts, customResolvers: opts.customResolvers })
+  const verifyResolution = createResolutionVerifier(fetchFromRegistry, opts)
   return {
     fetchers: createFetchers(fetchFromRegistry, getAuthHeader, opts),
     resolve,
     clearResolutionCache,
+    verifyResolution,
   }
 }
 

installing/commands/src/fetch.ts

@@ -70,6 +70,7 @@ export async function handler (opts: FetchCommandOptions): Promise<void> {
     pruneStore: true,
     storeController: store.ctrl,
     storeDir: store.dir,
+    verifyResolution: store.verifyResolution,
     // Hoisting is skipped anyway,
     // so we store these empty patterns in node_modules/.modules.yaml
     // to let the subsequent install know that hoisting should be performed.

installing/commands/src/import/index.ts

@@ -186,6 +186,7 @@ export async function handler (
     preferredVersions,
     storeController: store.ctrl,
     storeDir: store.dir,
+    verifyResolution: store.verifyResolution,
   }
   await install(manifest, installOpts)
 }

installing/commands/src/installDeps.ts

@@ -279,6 +279,7 @@ export async function installDeps (
     skipRuntimes: opts.runtime === false,
     storeController: store.ctrl,
     storeDir: store.dir,
+    verifyResolution: store.verifyResolution,
     workspacePackages,
     preferredVersions: opts.packageVulnerabilityAudit ? preferNonvulnerablePackageVersions(opts.packageVulnerabilityAudit) : undefined,
   }

installing/commands/src/recursive.ts

@@ -32,6 +32,7 @@ import {
 import { logger } from '@pnpm/logger'
 import { filterDependenciesByType } from '@pnpm/pkg-manifest.utils'
 import type { PreferredVersions } from '@pnpm/resolving.resolver-base'
+import type { ResolutionVerifier } from '@pnpm/resolving.resolver-base'
 import { createStoreController, type CreateStoreControllerOptions } from '@pnpm/store.connection-manager'
 import type { StoreController } from '@pnpm/store.controller'
 import type {
@@ -114,6 +115,7 @@ export type RecursiveOptions = CreateStoreControllerOptions & Pick<Config,
   storeControllerAndDir?: {
     ctrl: StoreController
     dir: string
+    verifyResolution?: ResolutionVerifier
   }
   pnpmfile: string[]
 } & Partial<
@@ -165,6 +167,7 @@ export async function recursive (
     storeController: store.ctrl,
     storeDir: store.dir,
     targetDependenciesField,
+    verifyResolution: store.verifyResolution,
     workspacePackages,
   }) as InstallOptions
 
@@ -296,6 +299,7 @@ export async function recursive (
     } = await mutateModules(mutatedImporters, {
       ...installOpts,
       storeController: store.ctrl,
+      verifyResolution: store.verifyResolution,
     })
     if (opts.save !== false) {
       const promises: Array<Promise<void>> = mutatedPkgs.map(async ({ originalManifest, manifest, rootDir }) => {
@@ -414,6 +418,7 @@ export async function recursive (
             }),
             configByUri: installOpts.configByUri,
             storeController: store.ctrl,
+            verifyResolution: store.verifyResolution,
           }
         )
         if (opts.save !== false) {

installing/commands/src/remove.ts

@@ -188,6 +188,7 @@ export async function handler (
     linkWorkspacePackagesDepth: opts.linkWorkspacePackages === 'deep' ? Infinity : opts.linkWorkspacePackages ? 0 : -1,
     storeController: store.ctrl,
     storeDir: store.dir,
+    verifyResolution: store.verifyResolution,
     include,
   })
   const allProjects = opts.allProjects ?? (

installing/deps-installer/src/install/extendInstallOptions.ts

@@ -11,7 +11,7 @@ import type { ProjectOptions } from '@pnpm/installing.context'
 import type { HoistingLimits } from '@pnpm/installing.deps-restorer'
 import type { IncludedDependencies } from '@pnpm/installing.modules-yaml'
 import type { LockfileObject } from '@pnpm/lockfile.fs'
-import type { WorkspacePackages } from '@pnpm/resolving.resolver-base'
+import type { ResolutionVerifier, WorkspacePackages } from '@pnpm/resolving.resolver-base'
 import type { StoreController } from '@pnpm/store.controller-types'
 import type {
   AllowedDeprecatedVersions,
@@ -175,6 +175,15 @@ export interface StrictInstallOptions {
   ci?: boolean
   minimumReleaseAge?: number
   minimumReleaseAgeExclude?: string[]
+  /**
+   * Optional verifier that re-checks each lockfile-pinned resolution
+   * against policies configured upstream (today: minimumReleaseAge strict
+   * mode). Constructed by `createClient` and surfaced via the
+   * `createStoreController` return; mutateModules invokes it once, right
+   * after the lockfile is loaded from disk. When omitted, no revalidation
+   * runs.
+   */
+  verifyResolution?: ResolutionVerifier
   trustPolicy?: TrustPolicy
   trustPolicyExclude?: string[]
   trustPolicyIgnoreAfter?: number

installing/deps-installer/src/install/index.ts

@@ -95,6 +95,7 @@ import {
 import { linkPackages } from './link.js'
 import { reportPeerDependencyIssues } from './reportPeerDependencyIssues.js'
 import { validateModules } from './validateModules.js'
+import { verifyLockfileResolutions } from './verifyLockfileResolutions.js'
 
 class LockfileConfigMismatchError extends PnpmError {
   constructor (outdatedLockfileSettingName: string) {
@@ -274,6 +275,11 @@ export async function mutateModules (
   maybeOpts: MutateModulesOptions
 ): Promise<MutateModulesResult> {
   const reporter = maybeOpts?.reporter
+  const detachReporter = (reporter != null) && typeof reporter === 'function'
+    ? () => {
+      streamParser.removeListener('data', reporter)
+    }
+    : () => {}
   if ((reporter != null) && typeof reporter === 'function') {
     streamParser.on('data', reporter)
   }
@@ -328,6 +334,26 @@ export async function mutateModules (
     }
   }
 
+  // Re-validate every entry in the lockfile against the policies the
+  // resolver chain was built with (today: minimumReleaseAge in strict mode
+  // via the npm verifier; the abstraction supports other resolvers
+  // attaching their own verifiers). The threat model is a lockfile that
+  // someone else resolved — committed to the repo, restored from a CI
+  // cache, etc. — bypassing the local resolver's policy filters; the local
+  // resolver's own filters already cover fresh resolution. We run this
+  // exactly once, right after the lockfile is loaded from disk, before any
+  // path branches.
+  try {
+    await verifyLockfileResolutions(ctx.wantedLockfile, opts.verifyResolution)
+  } catch (err) {
+    // verifyLockfileResolutions is the one throw site in this function
+    // that's part of normal user-facing operation (a rejected lockfile);
+    // other throws here are unexpected. Detach the reporter listener so
+    // long-lived processes don't leak it on every rejected install.
+    detachReporter()
+    throw err
+  }
+
   if (opts.hooks.preResolution) {
     for (const preResolution of opts.hooks.preResolution) {
       // eslint-disable-next-line no-await-in-loop
@@ -415,9 +441,7 @@ export async function mutateModules (
     packageNames: ignoredBuilds ? dedupePackageNamesFromIgnoredBuilds(ignoredBuilds) : [],
   })
 
-  if ((reporter != null) && typeof reporter === 'function') {
-    streamParser.removeListener('data', reporter)
-  }
+  detachReporter()
 
   return {
     updatedCatalogs: result.updatedCatalogs,