@pnpm/installing.deps-installer 1101.1.2 → 1101.3.0

package/lib/install/verifyLockfileResolutions.d.ts

@@ -0,0 +1,59 @@
+import type { LockfileObject } from '@pnpm/lockfile.fs';
+import type { ResolutionPolicyViolation, ResolutionVerifier } from '@pnpm/resolving.resolver-base';
+export type { ResolutionPolicyViolation };
+export interface VerifyLockfileResolutionsOptions {
+    concurrency?: number;
+    /**
+     * pnpm's on-disk cache directory. When set together with
+     * `lockfilePath`, verification results are memoized in
+     * `<cacheDir>/lockfile-verified.jsonl` and the gate short-circuits on
+     * a repeat run against an unchanged lockfile + same-or-stricter
+     * policy. Omit to disable the cache entirely (every call rehashes
+     * the lockfile and re-verifies).
+     */
+    cacheDir?: string;
+    /** Absolute path of the lockfile being verified. Used by the cache's stat shortcut. */
+    lockfilePath?: string;
+}
+/**
+ * Policy-neutral pass that asks every resolver-supplied
+ * {@link ResolutionVerifier} to check every entry in a lockfile loaded
+ * from disk. Iteration runs before resolution decisions are touched and
+ * before any tarball is fetched, so a lockfile whose entries were
+ * resolved elsewhere (committed to the repo, restored from a cache,
+ * etc.) under a weaker or absent policy cannot reach the filesystem.
+ * Fresh local resolution is covered by the resolver's own per-version
+ * filter.
+ *
+ * Each verifier handles its own protocol short-circuit inside `verify`
+ * (returning `{ ok: true }` for resolutions outside its scope), so the
+ * fan-out is policy-neutral and dispatch-free at this layer.
+ *
+ * Designed for fail-closed semantics at the verifier level: a verifier
+ * that can't confirm a resolution is expected to return `{ ok: false }`
+ * rather than passing silently — otherwise a registry hiccup or an
+ * unpublished version would re-open the bypass.
+ *
+ * No-op when `verifiers` is empty.
+ *
+ * When `options.cacheDir` and `options.lockfilePath` are both
+ * provided, an unchanged lockfile that has already been verified
+ * under the same (or stricter) policy short-circuits the registry
+ * round-trip entirely — see {@link tryLockfileVerificationCache} for
+ * the lookup logic.
+ */
+export declare function verifyLockfileResolutions(lockfile: LockfileObject, verifiers: ResolutionVerifier[], options?: VerifyLockfileResolutionsOptions): Promise<void>;
+/**
+ * Collect-mode sibling of {@link verifyLockfileResolutions}: runs the
+ * same fan-out over every verifier and every lockfile entry, but
+ * returns the violations as data instead of throwing on the first batch.
+ * No cache lookup or write — the throw-mode `verifyLockfileResolutions`
+ * is what populates / honors the cache; this is for callers that need
+ * to inspect violations (auto-collect into `minimumReleaseAgeExclude`,
+ * the strict-mode interactive prompt, future resolver-specific
+ * policies).
+ *
+ * Returns an empty array when `verifiers` is empty or the lockfile has
+ * no packages, so callers don't need a separate emptiness check.
+ */
+export declare function collectResolutionPolicyViolations(lockfile: LockfileObject, verifiers: ResolutionVerifier[], options?: Pick<VerifyLockfileResolutionsOptions, 'concurrency'>): Promise<ResolutionPolicyViolation[]>;

package/lib/install/verifyLockfileResolutions.js

@@ -0,0 +1,225 @@
+import { lockfileVerificationLogger } from '@pnpm/core-loggers';
+import { hashObject } from '@pnpm/crypto.object-hasher';
+import { PnpmError } from '@pnpm/error';
+import { nameVerFromPkgSnapshot } from '@pnpm/lockfile.utils';
+import pLimit from 'p-limit';
+import { recordVerification, tryLockfileVerificationCache, } from './verifyLockfileResolutionsCache.js';
+// Cap the per-entry breakdown so a verifier rejecting hundreds of entries
+// (e.g. a poisoned lockfile) doesn't flood the terminal / CI log; the full
+// count is in the header and the remainder is summarized at the end.
+const MAX_VIOLATIONS_TO_PRINT = 20;
+// 16 mirrors the floor of pnpm's package-requester network-concurrency
+// (Math.min(64, Math.max(workers*3, 16))); keep them aligned so the
+// verification pass doesn't push past what the rest of the install respects.
+const DEFAULT_CONCURRENCY = 16;
+/**
+ * Policy-neutral pass that asks every resolver-supplied
+ * {@link ResolutionVerifier} to check every entry in a lockfile loaded
+ * from disk. Iteration runs before resolution decisions are touched and
+ * before any tarball is fetched, so a lockfile whose entries were
+ * resolved elsewhere (committed to the repo, restored from a cache,
+ * etc.) under a weaker or absent policy cannot reach the filesystem.
+ * Fresh local resolution is covered by the resolver's own per-version
+ * filter.
+ *
+ * Each verifier handles its own protocol short-circuit inside `verify`
+ * (returning `{ ok: true }` for resolutions outside its scope), so the
+ * fan-out is policy-neutral and dispatch-free at this layer.
+ *
+ * Designed for fail-closed semantics at the verifier level: a verifier
+ * that can't confirm a resolution is expected to return `{ ok: false }`
+ * rather than passing silently — otherwise a registry hiccup or an
+ * unpublished version would re-open the bypass.
+ *
+ * No-op when `verifiers` is empty.
+ *
+ * When `options.cacheDir` and `options.lockfilePath` are both
+ * provided, an unchanged lockfile that has already been verified
+ * under the same (or stricter) policy short-circuits the registry
+ * round-trip entirely — see {@link tryLockfileVerificationCache} for
+ * the lookup logic.
+ */
+export async function verifyLockfileResolutions(lockfile, verifiers, options) {
+    if (verifiers.length === 0)
+        return;
+    if (!lockfile.packages)
+        return;
+    // Caching kicks in only when the caller surfaced both a writable
+    // cache directory and the lockfile's absolute path — that's the
+    // production wiring; unit tests that skip them get the gate without
+    // memoization and still exercise the same code path.
+    const cache = options?.cacheDir && options?.lockfilePath
+        ? { cacheDir: options.cacheDir, lockfilePath: options.lockfilePath }
+        : undefined;
+    let cachePrecomputed;
+    // hashObject streams and is key-order-stable, unlike JSON.stringify.
+    let cachedHash;
+    const hashLockfile = () => {
+        if (cachedHash == null)
+            cachedHash = hashObject(lockfile);
+        return cachedHash;
+    };
+    if (cache) {
+        const result = tryLockfileVerificationCache(cache.cacheDir, {
+            lockfilePath: cache.lockfilePath,
+            verifiers,
+            hashLockfile,
+        });
+        if (result.hit)
+            return;
+        cachePrecomputed = result.precomputed;
+    }
+    // Emit started/done around the actual verification pass — the
+    // round-trip can be slow on a cold registry cache, and the cached
+    // short-circuit above doesn't reach this branch, so a user only
+    // sees these messages on installs that are doing real work.
+    // A degenerate lockfile where every snapshot fails the
+    // name/version extraction (so candidates is empty) skips emission
+    // entirely — no work, no noise.
+    const candidates = collectCandidates(lockfile);
+    if (candidates.size === 0) {
+        if (cache) {
+            recordVerification(cache.cacheDir, {
+                lockfilePath: cache.lockfilePath,
+                verifiers,
+                hashLockfile,
+            }, cachePrecomputed);
+        }
+        return;
+    }
+    const startedAt = Date.now();
+    lockfileVerificationLogger.debug({
+        status: 'started',
+        entries: candidates.size,
+        lockfilePath: options?.lockfilePath,
+    });
+    // Guarantee a terminal `done` or `failed` event on every exit path
+    // that emitted `started`. Without this, an unexpected throw from the
+    // registry fan-out (or the policy-violation throw below) would leave
+    // the transient "Verifying lockfile…" line as the last frame the
+    // reporter rendered for this block, hanging spinner-style above the
+    // failure output.
+    let terminalStatus = 'failed';
+    try {
+        const violations = await iterateLockfileViolations(candidates, verifiers, options?.concurrency);
+        if (violations.length === 0) {
+            terminalStatus = 'done';
+            // Persist the success so the next install can stat-only the lockfile.
+            if (cache) {
+                recordVerification(cache.cacheDir, {
+                    lockfilePath: cache.lockfilePath,
+                    verifiers,
+                    hashLockfile,
+                }, cachePrecomputed);
+            }
+            return;
+        }
+        throw buildVerificationError(violations);
+    }
+    finally {
+        lockfileVerificationLogger.debug({
+            status: terminalStatus,
+            entries: candidates.size,
+            elapsedMs: Date.now() - startedAt,
+            lockfilePath: options?.lockfilePath,
+        });
+    }
+}
+function buildVerificationError(violations) {
+    // Stable order so the error output is deterministic.
+    violations.sort((a, b) => `${a.name}@${a.version}`.localeCompare(`${b.name}@${b.version}`));
+    // Pick the throw code: a single-code batch keeps the per-policy code
+    // (so existing handlers / docs / search keywords still route correctly);
+    // a mixed batch (e.g. minimumReleaseAge + trust-downgrade on the same
+    // lockfile) escalates to the generic `LOCKFILE_RESOLUTION_VERIFICATION`
+    // and the per-entry code goes into the breakdown so the user can see
+    // which policy each entry tripped.
+    const distinctCodes = new Set(violations.map((v) => v.code));
+    const isMixed = distinctCodes.size > 1;
+    const errorCode = isMixed ? 'LOCKFILE_RESOLUTION_VERIFICATION' : violations[0].code;
+    const visible = violations.slice(0, MAX_VIOLATIONS_TO_PRINT);
+    const omitted = violations.length - visible.length;
+    const formatEntry = isMixed
+        ? (v) => `  ${v.name}@${v.version} [${v.code}] ${v.reason}`
+        : (v) => `  ${v.name}@${v.version} ${v.reason}`;
+    const breakdown = visible.map(formatEntry).join('\n');
+    const details = omitted > 0
+        ? `${breakdown}\n  …and ${omitted} more`
+        : breakdown;
+    return new PnpmError(errorCode, `${violations.length} lockfile entries failed verification:\n${details}`, {
+        hint: 'The lockfile contains entries that the active policies reject. ' +
+            'This can mean the lockfile is stale, or that someone committed a ' +
+            'lockfile that bypassed the policy locally — inspect recent changes ' +
+            'to pnpm-lock.yaml before trusting it. If the changes look expected, ' +
+            'run "pnpm clean --lockfile" and then "pnpm install" to rebuild from ' +
+            'a fresh resolution. Alternatively, relax the policy that flagged ' +
+            'them.',
+    });
+}
+/**
+ * Collect-mode sibling of {@link verifyLockfileResolutions}: runs the
+ * same fan-out over every verifier and every lockfile entry, but
+ * returns the violations as data instead of throwing on the first batch.
+ * No cache lookup or write — the throw-mode `verifyLockfileResolutions`
+ * is what populates / honors the cache; this is for callers that need
+ * to inspect violations (auto-collect into `minimumReleaseAgeExclude`,
+ * the strict-mode interactive prompt, future resolver-specific
+ * policies).
+ *
+ * Returns an empty array when `verifiers` is empty or the lockfile has
+ * no packages, so callers don't need a separate emptiness check.
+ */
+export async function collectResolutionPolicyViolations(lockfile, verifiers, options) {
+    if (verifiers.length === 0)
+        return [];
+    if (!lockfile.packages)
+        return [];
+    return iterateLockfileViolations(collectCandidates(lockfile), verifiers, options?.concurrency);
+}
+// depPath can include peer-dependency and patch_hash suffixes (e.g.
+// `react@18.0.0(peer)(patch_hash=…)`); the same (name, version) pair may
+// therefore appear multiple times. Dedupe so we issue at most one
+// verification per package version.
+//
+// Include a serialization of `resolution` in the key so two entries that
+// share a (name, version) but differ in *what* was resolved (e.g. one
+// pinned via npm, another via a git URL under the same alias) don't
+// collapse: if the wrong shape wins the dedup, a protocol-scoped
+// verifier short-circuits on the surviving entry and the real one is
+// never checked.
+function collectCandidates(lockfile) {
+    const candidates = new Map();
+    for (const [depPath, snapshot] of Object.entries(lockfile.packages ?? {})) {
+        const { name, version } = nameVerFromPkgSnapshot(depPath, snapshot);
+        if (!name || !version)
+            continue;
+        const key = `${name}@${version}@${JSON.stringify(snapshot.resolution)}`;
+        candidates.set(key, {
+            name,
+            version,
+            resolution: snapshot.resolution,
+        });
+    }
+    return candidates;
+}
+async function iterateLockfileViolations(candidates, verifiers, concurrency) {
+    const violations = [];
+    const limit = pLimit(concurrency ?? DEFAULT_CONCURRENCY);
+    await Promise.all(Array.from(candidates.values(), ({ name, version, resolution }) => limit(async () => {
+        // Fan out across every active verifier; each handles its own
+        // protocol short-circuit (e.g. the npm verifier returns ok:true for
+        // git resolutions). We stop at the first failure per entry so a
+        // multi-verifier setup doesn't produce duplicate violations for the
+        // same (name, version).
+        for (const verifier of verifiers) {
+            // eslint-disable-next-line no-await-in-loop
+            const result = await verifier.verify(resolution, { name, version });
+            if (!result.ok) {
+                violations.push({ name, version, resolution, code: result.code, reason: result.reason });
+                break;
+            }
+        }
+    })));
+    return violations;
+}
+//# sourceMappingURL=verifyLockfileResolutions.js.map

package/lib/install/verifyLockfileResolutionsCache.d.ts

@@ -0,0 +1,80 @@
+import type { ResolutionVerifier } from '@pnpm/resolving.resolver-base';
+/**
+ * Subset of {@link ResolutionVerifier} the cache layer needs: the
+ * verifier's `policy` contribution plus the `canTrustPastCheck`
+ * comparator. `verify` is intentionally absent — the cache never runs
+ * verifiers, it just decides whether a previous run is still
+ * trustworthy.
+ */
+export type VerifierCacheIdentity = Pick<ResolutionVerifier, 'policy' | 'canTrustPastCheck'>;
+export interface CacheLookupResult {
+    hit: boolean;
+    /**
+     * stat + hash already computed during the lookup. When the caller
+     * follows up with {@link recordVerification} after running the gate,
+     * passing these back avoids re-stat'ing and (especially) re-hashing
+     * the lockfile a second time. Fields are undefined when the lookup
+     * couldn't (or didn't need to) compute them — `recordVerification`
+     * falls back to computing what's missing.
+     */
+    precomputed: {
+        stat?: LockfileStat;
+        hash?: string;
+    };
+}
+interface LockfileStat {
+    size: number;
+    mtimeNs: string;
+    inode: string;
+}
+export interface LockfileVerificationCacheKey {
+    lockfilePath: string;
+    verifiers: readonly VerifierCacheIdentity[];
+    /**
+     * Lazy: returns a stable hex hash of the in-memory lockfile. The
+     * cache invokes this only when the stat shortcut doesn't apply (the
+     * lockfile is at a new path, or its stat has drifted from the
+     * cached record). When the stat shortcut hits, the in-memory hash is
+     * never computed.
+     */
+    hashLockfile: () => string;
+}
+/**
+ * Try to confirm a cached verification covers the lockfile as it
+ * currently sits on disk and the policies currently in effect. Returns
+ * `{ hit: true }` to skip the gate; `{ hit: false }` means the caller
+ * should run the verifier and persist the result with
+ * {@link recordVerification}.
+ *
+ * Lookup order:
+ *
+ * 1. **Stat shortcut** — if we've previously verified this exact path
+ *    with these exact stat values, trust the cached hash and skip
+ *    reading the lockfile.
+ * 2. **Content lookup** — hash the lockfile and look up by hash.
+ *    Catches the worktree case (same content, different path) and
+ *    CI checkouts where stat fields got reset. Refreshes the
+ *    stat-shortcut entry on hit so the next install at this path
+ *    skips the hash.
+ *
+ * Every active verifier must agree the cached policy snapshot is still
+ * trustworthy under what it currently demands; if any rejects, the
+ * full gate runs.
+ */
+export declare function tryLockfileVerificationCache(cacheDir: string, key: LockfileVerificationCacheKey): CacheLookupResult;
+/**
+ * Persist a successful verification. Called after the gate passes; the
+ * lockfile is hashed once and the resulting record is appended to the
+ * cache file. If the file is past {@link MAX_CACHE_ENTRIES}, it is
+ * rewritten keeping the most recent entries.
+ *
+ * Reuses `precomputed` values from a prior
+ * {@link tryLockfileVerificationCache} lookup so we don't re-stat or
+ * (especially) re-hash the lockfile a second time on the miss-then-
+ * record path.
+ */
+export declare function recordVerification(cacheDir: string, key: LockfileVerificationCacheKey, precomputed?: {
+    stat?: LockfileStat;
+    hash?: string;
+}): void;
+export {};