checkly 8.22.0 → 8.23.0

package/dist/services/embedded-packages/materializer.js

@@ -6,10 +6,12 @@ import Debug from 'debug';
 import PQueue from 'p-queue';
 import { assignProxy } from '../proxy.js';
 import { TarballCache, lookupNpmCacache } from './cache.js';
-import { verifyIntegrity } from './integrity.js';
-import { UnsupportedLockfileError, loadLockfilePackages, } from './lockfile-packages.js';
-import { defaultNpmrcPaths, loadNpmrcConfig, resolveAuthHeader, resolveRegistryUrl } from './npmrc.js';
-import { InvalidEmbeddedPackageSpecError, parseEmbeddedPackageSpec, specMatchesPackageName, } from './spec.js';
+import { downloadFailureHint, capList, describeConfigKeys, describeUnreadableConfig, describeUnusableUrlOrigin, redactUrl, } from './diagnostics.js';
+import { integrityHashToHex, strongestIntegrityHash, verifyIntegrity } from './integrity.js';
+import { UnsupportedLockfileError, isPnpmLockfile, loadLockfilePackages, } from './lockfile-packages.js';
+import { defaultNpmrcPaths, loadNpmrcConfig, pnpmAuthIniPath, resolveAuthHeader, resolveRegistry, } from './npmrc.js';
+import { InvalidEmbeddedPackageSpecError, parseEmbeddedPackageSpec, specLooselyMatchesPackage, specMatchesPackage, specMatchesPackageName, } from './spec.js';
+import { COMPOSABLE_URL_REQUIREMENT, parseFetchableUrl } from './url.js';
 const debug = Debug('checkly:cli:services:embedded-packages');
 /**
  * The directory inside the code bundle where embedded package tarballs
@@ -27,40 +29,39 @@ const DOWNLOAD_CONCURRENCY = 5;
 const DOWNLOAD_TIMEOUT_MS = 120_000;
 const MAX_TARBALL_BYTES = 1024 * 1024 * 1024;
 /**
- * Joins up to 8 items, appending `<overflow>N more` for the rest — the
- * uniform truncation for user-facing lists of packages, versions and
- * reasons.
+ * Wraps an axios error from a registry request in an EmbeddedPackageError,
+ * appending the HTTP status and whatever the caller's hint makes of it.
+ * `message` is the action-specific prefix (e.g. "Failed to download …").
  */
-function capList(items, separator, overflow) {
-    const shown = items.slice(0, 8).join(separator);
-    return items.length > 8 ? `${shown}${overflow}${items.length - 8} more` : shown;
+function registryHttpError(err, message, hint = () => '') {
+    const status = err?.response?.status;
+    const statusHint = status !== undefined ? ` (HTTP ${status})` : '';
+    return new EmbeddedPackageError(`${message}${statusHint}.${hint(status)}`, { cause: err });
 }
 /**
- * Removes userinfo credentials from a URL so it can be safely included in
- * error messages and logs (a registry URL may embed a token).
+ * Whether a URL carries credentials in its userinfo component. axios sends
+ * those itself — and drops any `Authorization` header when it does — so a
+ * failure hint that only consulted the npm config would contradict what was
+ * actually on the wire.
+ *
+ * Only called with a URL the caller has already parsed successfully.
  */
-function redactUrl(url) {
-    try {
-        const parsed = new URL(url);
-        parsed.username = '';
-        parsed.password = '';
-        return parsed.toString();
-    }
-    catch {
-        // Not parseable as a URL (e.g. a scheme-less registry entry) — strip
-        // anything that looks like a userinfo segment before displaying it.
-        return url.replace(/(^|\/\/)[^/@\s]+@/, '$1');
-    }
+function hasUrlCredentials(url) {
+    const parsed = new URL(url);
+    return parsed.username !== '' || parsed.password !== '';
 }
 /**
  * Resolves the configured `bundle.packages.embed` specs against the
  * workspace lockfile (plan) and sources the selected tarballs into the CLI
- * cache (materialize), through a chain of CLI cache → npm cacache →
+ * cache (materializeTarballs), through a chain of CLI cache → npm cacache →
  * registry download, always verified against the lockfile integrity.
  *
- * Both stages memoize their in-flight promise: multiple Playwright checks
- * bundle concurrently, and validation and bundling share one instance per
- * parsed project, so the work runs exactly once.
+ * The plan memoizes its in-flight promise: validation and bundling share
+ * one instance per parsed project, so the (purely local) resolution runs
+ * exactly once. Materialization has a single caller — the Bundler, at
+ * finalize time, after the bundled lockfile has been pruned — which passes
+ * the subset of the plan the shipped lockfile still references, so
+ * pruned-away tarballs are never downloaded.
  */
 export class EmbeddedPackagesMaterializer {
     #options;
@@ -68,7 +69,18 @@ export class EmbeddedPackagesMaterializer {
     #env;
     #homedir;
     #plan;
-    #materialized;
+    /**
+     * In-flight tarball sourcing, keyed by the strongest integrity hash —
+     * the same addressing the cache stores under. Plan entries can share
+     * tarball content (two versions published with identical bytes), and the
+     * download queue runs them concurrently; sharing one sourcing promise
+     * per distinct hash fetches and writes such content once instead of
+     * racing identical writes onto one cache path. Entries are dropped as
+     * soon as sourcing settles: later materializations must read through the
+     * cache, whose reads re-verify content, rather than trust a memoized
+     * path.
+     */
+    #inFlightTarballs = new Map();
     constructor(options) {
         this.#options = options;
         this.#env = options.env ?? process.env;
@@ -83,9 +95,48 @@ export class EmbeddedPackagesMaterializer {
         this.#plan ??= this.#createPlan();
         return this.#plan;
     }
-    materialize() {
-        this.#materialized ??= this.#materializeAll();
-        return this.#materialized;
+    /**
+     * Sources the given subset of the planned tarballs (CLI cache → npm
+     * cacache → registry download, verified against the lockfile integrity).
+     * Lets the caller materialize only the tarballs a pruned bundled lockfile
+     * still references, so pruned-away packages are never downloaded.
+     */
+    async materializeTarballs(tarballs) {
+        const { issues } = await this.plan();
+        // Commands validate before bundling and exit on fatal diagnostics, so
+        // this is a defensive backstop for direct/programmatic use. Checked
+        // before the empty-list short-circuit: an invalid configuration must
+        // not pass silently just because nothing was requested.
+        if (issues.length > 0) {
+            throw new EmbeddedPackageError(`Cannot embed packages due to configuration issues:\n\n`
+                + issues.map(issue => `  ${issue.message}`).join('\n'));
+        }
+        if (tarballs.length === 0) {
+            return [];
+        }
+        // Safe to assert both: a missing lockfile is a plan issue, and issues
+        // abort above.
+        const lockfilePath = this.#options.lockfilePath;
+        const pnpmAuthFile = pnpmAuthIniPath(this.#env, process.platform, this.#homedir);
+        const pnpmAuthFilePreferred = isPnpmLockfile(lockfilePath);
+        debug('pnpm auth file %s (preferred: %s)', pnpmAuthFile, pnpmAuthFilePreferred);
+        const npmrc = await loadNpmrcConfig(defaultNpmrcPaths({
+            workspaceRoot: this.#projectRoot,
+            homedir: this.#homedir,
+            contextDir: this.#options.contextDir,
+            pnpmAuthFile,
+            pnpmAuthFilePreferred,
+        }), this.#env);
+        const queue = new PQueue({ concurrency: DOWNLOAD_CONCURRENCY });
+        return await queue.addAll(tarballs.map(tarball => async () => {
+            const { filePath, integrity } = await this.#obtainTarball(tarball, npmrc);
+            return {
+                ...tarball,
+                integrity,
+                filePath,
+                archivePath: `${EMBEDDED_PACKAGES_ARCHIVE_DIR}/${tarball.archiveFilename}`,
+            };
+        }));
     }
     async #createPlan() {
         const issues = [];
@@ -137,12 +188,74 @@ export class EmbeddedPackagesMaterializer {
         const registryKeys = new Set(packages.registry.map(entry => `${entry.name}@${entry.version}`));
         const relevantExcluded = packages.excluded.filter(entry => entry.version === undefined || !registryKeys.has(`${entry.name}@${entry.version}`));
         const tarballs = new Map();
-        for (const spec of specs) {
+        for (const [index, spec] of specs.entries()) {
+            // Exclusions select nothing themselves; they subtract from the entries
+            // before them, via the kept() filter below. One that removes nothing is
+            // a valid no-op rather than an error, unlike an unresolvable inclusion.
+            if (spec.exclude) {
+                // Matching nothing is a valid outcome, so a misspelled `!` entry
+                // cannot be an error — but it silently fails to keep a package out,
+                // which is worth a line on the debug channel.
+                if (!packages.registry.some(entry => specMatchesPackageName(spec, entry.name))
+                    && !relevantExcluded.some(entry => specMatchesPackageName(spec, entry.name))) {
+                    debug('exclusion %s matches no package in the lockfile', spec.raw);
+                }
+                continue;
+            }
+            // Entries apply in order, so only the `!` entries that come after this
+            // one take anything away from it. Filtering the matches up front,
+            // rather than pruning the finished plan, keeps the diagnostics below in
+            // step with what actually ships: an entry never warns about, or fails
+            // over, a package the configuration goes on to exclude. This applies
+            // the ordered rule `patternsSelectName` (spec.ts) defines canonically,
+            // generalized to embed's version pins via specMatchesPackage — the
+            // name-only helper cannot express `!bar@2.0.0`. A change to the
+            // exclusion semantics must land in both.
+            const laterExclusions = specs.slice(index + 1).filter(other => other.exclude);
+            const kept = (entries) => entries.filter(entry => !laterExclusions.some(other => specMatchesPackage(other, entry)));
+            // nameMatches stays unfiltered: it only feeds the diagnostics below,
+            // which describe the lockfile as it is — a mistyped pin should still be
+            // told which versions exist, even when an unrelated exclusion removed
+            // them from what this entry embeds.
             const nameMatches = packages.registry.filter(entry => specMatchesPackageName(spec, entry.name));
-            const candidates = nameMatches
-                .filter(entry => spec.version === undefined || entry.version === spec.version);
-            const nameExcluded = relevantExcluded.filter(entry => specMatchesPackageName(spec, entry.name));
-            const looseExcluded = nameExcluded.filter(entry => spec.version === undefined || entry.version === undefined || entry.version === spec.version);
+            const allCandidates = packages.registry.filter(entry => specMatchesPackage(spec, entry));
+            // The two sets differ only in version-less entries (workspace links,
+            // git resolutions), which the loose one keeps: such an entry matches
+            // any pin, so it can describe a pinned spec's failure but must not be
+            // what silences it. Both feed the diagnostics below, at different
+            // rungs of the ladder.
+            const allLooseExcluded = relevantExcluded.filter(entry => specLooselyMatchesPackage(spec, entry));
+            const allStrictExcluded = relevantExcluded.filter(entry => specMatchesPackage(spec, entry));
+            const candidates = kept(allCandidates);
+            const looseExcluded = kept(allLooseExcluded);
+            const strictExcluded = kept(allStrictExcluded);
+            // Everything this entry could have embedded was removed by a later `!`
+            // entry, which is the configured outcome: it embeds nothing and reports
+            // nothing instead of looking unresolvable. Two ways to get there, and
+            // both require the exclusions to be the whole reason: an entry that had
+            // embeddable matches is silent once every one of them is excluded, and
+            // an entry that only ever reached un-embeddable matches is silent only
+            // once every one of *those* is excluded — one that survives still
+            // carries the not-embeddable error it would raise on its own.
+            //
+            // Comparing at the version-filtered level matters: an entry disabled by
+            // appending its own pin as an exclusion ('bar@2.0.0', '!bar@2.0.0')
+            // would otherwise stay alive on the package's other versions and fail
+            // with a version-not-found error that names them as the only ones in
+            // the lockfile.
+            //
+            // An entry emptied this way also drops the skip warning for any
+            // un-embeddable package it reached but did not exclude. That is a
+            // deliberate trade: keeping the warning means keeping the entry alive
+            // past this point, where an un-embeddable match with nothing left to
+            // embed alongside it is a fatal error. The debug line below is what
+            // explains an entry that embedded nothing.
+            if (candidates.length === 0
+                && (allCandidates.length > 0
+                    || (allStrictExcluded.length > 0 && strictExcluded.length === 0))) {
+                debug('spec %s: embeds nothing, later exclusions removed every embeddable match (reached: %j)', spec.raw, [...allCandidates, ...allStrictExcluded].map(entry => `${entry.name}@${entry.version}`));
+                continue;
+            }
             if (candidates.length === 0) {
                 // Excluded entries matching the exact pin (or any entry, when
                 // unpinned) carry the most actionable reason and win; a version
@@ -150,10 +263,14 @@ export class EmbeddedPackagesMaterializer {
                 // Version-less excluded entries (e.g. workspace links) are a last
                 // resort, so a pinned spec is never blamed on one while a better
                 // explanation exists.
-                const strictExcluded = nameExcluded.filter(entry => spec.version === undefined || entry.version === spec.version);
+                // The fallback reads the unfiltered set, for the same reason
+                // nameMatches is unfiltered: an entry that still has to fail should
+                // fail with the most accurate reason the lockfile offers, and a
+                // version-less excluded entry (a git resolution, a workspace link)
+                // is often the only thing that explains it.
                 const excludedMatches = strictExcluded.length > 0
                     ? strictExcluded
-                    : nameMatches.length === 0 ? looseExcluded : [];
+                    : nameMatches.length === 0 ? allLooseExcluded : [];
                 if (excludedMatches.length > 0) {
                     const reasons = capList([...new Set(excludedMatches.map(entry => entry.reason))], '; ', '; and ');
                     issues.push({
@@ -175,7 +292,7 @@ export class EmbeddedPackagesMaterializer {
                     });
                 }
                 else {
-                    const hint = spec.namePattern !== undefined
+                    const hint = spec.wildcard
                         ? `pattern matches its name${spec.version !== undefined ? ' and the version is spelled correctly' : ''}`
                         : `name ${spec.version !== undefined ? 'and version are' : 'is'} spelled correctly`;
                     issues.push({
@@ -203,7 +320,7 @@ export class EmbeddedPackagesMaterializer {
                     + ` be embedded as registry tarballs and were skipped: ${capList(names, ', ', ' and ')}.`
                     + ` The runner must be able to fetch these itself.`);
             }
-            if (spec.namePattern !== undefined) {
+            if (spec.wildcard) {
                 // Wildcards select invisibly, but only the debug log says what they
                 // selected. Selections that need attention surface louder: a
                 // pattern matching nothing is a fatal validation issue, and matches
@@ -217,6 +334,16 @@ export class EmbeddedPackagesMaterializer {
                 });
             }
         }
+        // Without exclusions every entry either embeds something or raises an
+        // issue, so an empty plan with nothing to report can only come from `!`
+        // entries — most likely a config that reads them as gitignore's implicit
+        // "everything except" rather than as a subtraction from what came
+        // before. Embedding nothing is not an error, but saying so beats letting
+        // the user find out from an install failure on the runner.
+        if (specs.length > 0 && tarballs.size === 0 && issues.length === 0) {
+            warnings.push(`No packages matched 'bundle.packages.embed', so nothing will be embedded into the code bundle.`
+                + ` An exclusion entry ('!...') only removes packages that the entries before it selected.`);
+        }
         debug('plan: %d tarballs, %d issues, %d warnings', tarballs.size, issues.length, warnings.length);
         return {
             tarballs: [...tarballs.values()].sort((a, b) => a.archiveFilename.localeCompare(b.archiveFilename)),
@@ -225,65 +352,281 @@ export class EmbeddedPackagesMaterializer {
             lockfilePath,
         };
     }
-    async #materializeAll() {
-        const { tarballs, issues } = await this.plan();
-        // Commands validate before bundling and exit on fatal diagnostics, so
-        // this is a defensive backstop for direct/programmatic use.
-        if (issues.length > 0) {
-            throw new EmbeddedPackageError(`Cannot embed packages due to configuration issues:\n\n`
-                + issues.map(issue => `  ${issue.message}`).join('\n'));
+    /**
+     * Resolves the registry a package comes from, refusing one nothing can be
+     * fetched from.
+     *
+     * The registry URL is checked before anything is composed onto it:
+     * `registry=https://` composes into `https://<package name>/...`, which
+     * parses cleanly with the package name as its HOST, so the request would
+     * go to whatever host bears that name. A query or fragment is refused for
+     * the mirror-image reason — it absorbs the path instead of the host.
+     */
+    #resolveFetchableRegistry(tarball, npmrc) {
+        const registry = resolveRegistry(npmrc.config, tarball.name, this.#env);
+        if (registry.usable) {
+            return registry;
         }
-        if (tarballs.length === 0) {
-            return [];
+        // One sentence covering every way it can fail — it parses or it does
+        // not, it has a host or it does not, its scheme is fetchable or it is
+        // not, it carries a query or it does not — because splitting them
+        // produced advice that was wrong for the case it did not cover:
+        // `file:///srv/mirror/` is absolute and has a protocol, and being told
+        // to add one sends the reader nowhere.
+        //
+        // The value is not echoed, for the same reason a composed URL is not:
+        // one this malformed could carry a credential anywhere in it.
+        throw new EmbeddedPackageError(`The registry URL for embedded package '${tarball.name}@${tarball.version}' is not usable:`
+            + ` it must be ${COMPOSABLE_URL_REQUIREMENT}.`
+            + ` It is configured by ${describeConfigKeys([registry.key], npmrc)}.`);
+    }
+    /**
+     * Rejects a tarball URL nothing can be fetched from, naming whoever
+     * handed it over. Only a URL this CLI did not compose can get here — see
+     * `RecordedUrlOrigin`.
+     *
+     * The offending value is deliberately not echoed: it is unusable by
+     * definition here, so nothing can reliably tell a credential in it from a
+     * path. Naming the source is both safe and more useful — that is where
+     * the reader goes to fix it.
+     */
+    #assertFetchableTarballUrl(url, tarball, npmrc, origin) {
+        if (parseFetchableUrl(url) !== undefined) {
+            return;
         }
-        // Safe to assert: a missing lockfile is a plan issue, and issues abort
-        // above.
-        const npmrcConfig = await loadNpmrcConfig(defaultNpmrcPaths(this.#projectRoot, this.#homedir, this.#options.contextDir), this.#env);
-        const queue = new PQueue({ concurrency: DOWNLOAD_CONCURRENCY });
-        const results = await queue.addAll(tarballs.map(tarball => async () => {
-            const filePath = await this.#obtainTarball(tarball, npmrcConfig);
-            return {
-                ...tarball,
-                filePath,
-                archivePath: `${EMBEDDED_PACKAGES_ARCHIVE_DIR}/${tarball.archiveFilename}`,
-            };
-        }));
-        return results;
+        throw new EmbeddedPackageError(`The tarball URL for embedded package '${tarball.name}@${tarball.version}'`
+            + ` is not a valid URL. ${describeUnusableUrlOrigin(origin, npmrc)}`);
+    }
+    async #obtainTarball(tarball, npmrc) {
+        let { integrity, tarballUrl } = tarball;
+        // Set when the URL below came from package metadata rather than the
+        // lockfile, so a failure blames the registry that served it instead of
+        // a lockfile that never mentioned it.
+        let metadataOrigin;
+        if (integrity === undefined) {
+            // yarn.lock plans carry no SRI tarball integrity (Berry checksums
+            // hash yarn's own cache archive); resolve it from the registry's
+            // per-version metadata before the caches can be consulted.
+            const dist = await this.#resolveDistFromRegistry(tarball, npmrc);
+            integrity = dist.integrity;
+            if (tarballUrl === undefined && dist.tarballUrl !== undefined) {
+                tarballUrl = dist.tarballUrl;
+                metadataOrigin = { metadata: { registryKey: dist.registryKey } };
+            }
+        }
+        // An integrity without a supported hash has no cache address to key
+        // the deduplication on, so it sources directly (and fails at download
+        // verification, since no supported hash can match the content).
+        const hash = strongestIntegrityHash(integrity);
+        if (hash === undefined) {
+            return { filePath: await this.#sourceTarball(tarball, integrity, tarballUrl, metadataOrigin, npmrc), integrity };
+        }
+        const key = `${hash.algorithm}:${integrityHashToHex(hash)}`;
+        let pending = this.#inFlightTarballs.get(key);
+        if (pending === undefined) {
+            pending = this.#sourceTarball(tarball, integrity, tarballUrl, metadataOrigin, npmrc);
+            this.#inFlightTarballs.set(key, pending);
+            // Dropped as soon as sourcing settles, whichever way: a later
+            // materialization must read through the cache's own verification,
+            // and a failed attempt must not poison a retry with its stored
+            // rejection.
+            pending.then(() => this.#inFlightTarballs.delete(key), () => this.#inFlightTarballs.delete(key));
+        }
+        return { filePath: await pending, integrity };
     }
-    async #obtainTarball(tarball, npmrcConfig) {
-        const cached = await this.#cache.get(tarball.integrity);
+    /**
+     * Sources one tarball's verified content into the CLI cache — CLI cache
+     * → npm cacache → registry download, verified against `integrity` — and
+     * returns its cache path.
+     *
+     * When concurrent plan entries share an integrity, only the first
+     * entry's identity reaches this method: the URL, registry, and any
+     * failure's wording all follow that entry, not whichever entry awaited
+     * the shared sourcing.
+     */
+    async #sourceTarball(tarball, integrity, tarballUrl, metadataOrigin, npmrc) {
+        const cached = await this.#cache.get(integrity);
         if (cached !== undefined) {
             debug('%s@%s: CLI cache hit', tarball.name, tarball.version);
             return cached;
         }
-        const fromNpmCacache = await lookupNpmCacache(tarball.integrity, this.#env, process.platform, this.#homedir);
+        const fromNpmCacache = await lookupNpmCacache(integrity, this.#env, process.platform, this.#homedir);
         if (fromNpmCacache !== undefined) {
             debug('%s@%s: npm cache hit', tarball.name, tarball.version);
-            return await this.#cache.put(tarball.integrity, fromNpmCacache);
+            return await this.#cache.put(integrity, fromNpmCacache);
+        }
+        // Where the URL came from decides who to blame for credentials embedded
+        // in it: a lockfile-recorded URL is the lockfile's, a derived one
+        // belongs to whichever config key configured the registry.
+        let url;
+        let urlOrigin;
+        if (tarballUrl !== undefined) {
+            url = tarballUrl;
+            // Safe to assert: a missing lockfile is a plan issue, and materialize
+            // aborts on issues before any tarball is obtained.
+            const recorded = metadataOrigin ?? { lockfile: this.#options.lockfilePath };
+            // Only a URL handed over already formed can be unusable: the one the
+            // else-branch composes is built on a registry checked beforehand.
+            this.#assertFetchableTarballUrl(url, tarball, npmrc, recorded);
+            urlOrigin = recorded;
         }
-        const url = tarball.tarballUrl ?? this.#deriveTarballUrl(tarball, npmrcConfig);
-        if (!URL.canParse(url)) {
-            throw new EmbeddedPackageError(`The tarball URL for embedded package '${tarball.name}@${tarball.version}'`
-                + ` is not a valid URL: '${redactUrl(url)}'. Check the 'registry' configuration`
-                + ` in your .npmrc (it must be an absolute URL including the protocol).`);
+        else {
+            const registry = this.#resolveFetchableRegistry(tarball, npmrc);
+            const basename = tarball.name.split('/').pop();
+            url = `${registry.url}${tarball.name}/-/${basename}-${tarball.version}.tgz`;
+            urlOrigin = { registryKey: registry.key };
         }
         debug('%s@%s: downloading from %s', tarball.name, tarball.version, redactUrl(url));
-        const content = await this.#download(tarball, url, npmrcConfig);
-        if (!verifyIntegrity(content, tarball.integrity)) {
+        const content = await this.#download(tarball, url, npmrc, urlOrigin);
+        if (!verifyIntegrity(content, integrity)) {
+            // For yarn.lock plans the integrity came from the registry's own
+            // metadata, not the lockfile, so name the right source to check.
+            const source = tarball.integrity === undefined
+                ? `the integrity hash the registry's metadata reported`
+                : `the integrity hash recorded in the lockfile`;
             throw new EmbeddedPackageError(`The tarball downloaded for embedded package '${tarball.name}@${tarball.version}'`
-                + ` from '${redactUrl(url)}' does not match the integrity hash recorded in the lockfile`
-                + ` ('${tarball.integrity}'). The registry may be serving a different artifact`
+                + ` from '${redactUrl(url)}' does not match ${source}`
+                + ` ('${integrity}'). The registry may be serving a different artifact`
                 + ` than the one the lockfile was created against.`);
         }
-        return await this.#cache.put(tarball.integrity, content);
+        return await this.#cache.put(integrity, content);
     }
-    #deriveTarballUrl(tarball, npmrcConfig) {
-        const registryUrl = resolveRegistryUrl(npmrcConfig, tarball.name, this.#env);
-        const basename = tarball.name.split('/').pop();
-        return `${registryUrl}${tarball.name}/-/${basename}-${tarball.version}.tgz`;
+    /**
+     * Resolves the npm tarball integrity (and canonical tarball URL) for a
+     * package whose lockfile cannot provide one. Tries the abbreviated
+     * per-version metadata route (`GET <registry>/<name>/<version>`) first,
+     * then falls back to the full packument (`GET <registry>/<name>`, whose
+     * `versions[version].dist` carries the same fields) — some private
+     * registry proxies serve only one of the two. The scope slash stays
+     * unencoded, matching npm's own use of these routes. The requests use
+     * the same registry resolution and credentials as the tarball download
+     * itself, so they add no trust beyond the download; the end-to-end
+     * content pin still holds because the package manager re-verifies its
+     * own lockfile checksums against the served content at install time.
+     */
+    async #resolveDistFromRegistry(tarball, npmrc) {
+        // Both routes are this URL plus the package name, so checking it covers
+        // them and the composed forms need no guard of their own.
+        const registry = this.#resolveFetchableRegistry(tarball, npmrc);
+        const versionUrl = `${registry.url}${tarball.name}/${tarball.version}`;
+        const packumentUrl = `${registry.url}${tarball.name}`;
+        // Per-version route: dist is at the document root.
+        const perVersion = await this.#fetchMetadataDist(tarball, npmrc, versionUrl, registry.key, data => data?.dist);
+        // Packument fallback (only when the per-version route yielded no dist,
+        // whether it 404'd or answered without one): dist is nested per version.
+        const packument = perVersion?.dist !== undefined
+            ? undefined
+            : await this.#fetchMetadataDist(tarball, npmrc, packumentUrl, registry.key, data => data?.versions?.[tarball.version]?.dist);
+        const dist = perVersion?.dist ?? packument?.dist;
+        if (dist === undefined) {
+            // Distinguish "the registry has nothing for us" from "it answered but
+            // this version is not in it": only the first can be an authorization
+            // failure, since a private registry hides packages the caller may not
+            // see behind a 404, and claiming so for the second sends the reader to
+            // rotate a token the registry just accepted.
+            const answered = perVersion !== undefined || packument !== undefined;
+            if (answered) {
+                throw new EmbeddedPackageError(`The registry metadata at '${redactUrl(versionUrl)}' does not describe embedded package`
+                    + ` '${tarball.name}@${tarball.version}', so its integrity could not be resolved.`
+                    + ` The version may have been unpublished, the registry may serve only some versions, or`
+                    + ` something in front of it — a proxy or an SSO gateway — may have answered instead of`
+                    + ` the registry.${describeUnreadableConfig(npmrc)}`);
+            }
+            const auth = resolveAuthHeader(npmrc.config, versionUrl, tarball.name, this.#env);
+            const sent = this.#sentCredentials(versionUrl, { registryKey: registry.key }, auth);
+            throw new EmbeddedPackageError(`The registry at '${redactUrl(versionUrl)}' has no metadata for embedded package`
+                + ` '${tarball.name}@${tarball.version}', so its integrity could not be resolved.`
+                + downloadFailureHint(404, sent, npmrc));
+        }
+        // Modern publishes carry an SRI `integrity`; very old ones only a hex
+        // sha1 `shasum`, which converts to a (weaker but supported) SRI hash.
+        const integrity = typeof dist.integrity === 'string' && dist.integrity !== ''
+            ? dist.integrity
+            : typeof dist.shasum === 'string' && /^[0-9a-f]{40}$/.test(dist.shasum)
+                ? `sha1-${Buffer.from(dist.shasum, 'hex').toString('base64')}`
+                : undefined;
+        if (integrity === undefined) {
+            throw new EmbeddedPackageError(`The registry metadata for embedded package '${tarball.name}@${tarball.version}'`
+                + ` (from '${redactUrl(versionUrl)}') provides no usable integrity hash, so the`
+                + ` downloaded tarball could not be verified.`);
+        }
+        return {
+            integrity,
+            registryKey: registry.key,
+            // The same cheap prefilter the lockfile readers apply, and no more:
+            // anything that survives it is checked properly by
+            // `#assertFetchableTarballUrl`, which reports a URL the registry
+            // returned rather than silently composing a different one.
+            tarballUrl: typeof dist.tarball === 'string' && /^https?:/.test(dist.tarball)
+                ? dist.tarball
+                : undefined,
+        };
+    }
+    /**
+     * Who supplied the credentials on a request, for the failure message.
+     *
+     * Userinfo embedded in the URL wins: axios sends that itself and drops
+     * the Authorization header when it does, so naming the config entry
+     * would name credentials that never reached the wire. A URL with no
+     * userinfo falls back to the config keys — including one derived from the
+     * default registry, whose URL carries none by construction.
+     */
+    #sentCredentials(url, origin, auth) {
+        if (hasUrlCredentials(url)) {
+            return { from: 'url', origin };
+        }
+        return auth !== undefined ? { from: 'config', keys: auth.keys } : undefined;
     }
-    async #download(tarball, url, npmrcConfig) {
-        const authHeader = resolveAuthHeader(npmrcConfig, url, this.#env);
+    /**
+     * Fetches one metadata URL and extracts its `dist` via `select`.
+     *
+     * Returns undefined on a 404 — distinct from `{ dist: undefined }`, which
+     * means the route answered but carried nothing usable. The caller needs
+     * both apart: only a route that never answered can be an authorization
+     * failure. Any other failure — auth, network, malformed response — throws,
+     * because retrying a different route would only mask it.
+     */
+    async #fetchMetadataDist(tarball, npmrc, url, registryKey, select) {
+        const auth = resolveAuthHeader(npmrc.config, url, tarball.name, this.#env);
+        // This URL is always one the CLI built from the registry.
+        const sent = this.#sentCredentials(url, { registryKey }, auth);
+        debug('%s@%s: resolving integrity from %s', tarball.name, tarball.version, redactUrl(url));
+        try {
+            const response = await axios.get(url, assignProxy(url, {
+                headers: {
+                    ...(auth !== undefined ? { authorization: auth.header } : {}),
+                },
+                timeout: DOWNLOAD_TIMEOUT_MS,
+            }));
+            return { dist: select(response.data) ?? undefined };
+        }
+        catch (err) {
+            if (err?.response?.status === 404) {
+                return undefined;
+            }
+            throw registryHttpError(err, `Failed to fetch registry metadata for embedded package`
+                + ` '${tarball.name}@${tarball.version}' from '${redactUrl(url)}'`, status => downloadFailureHint(status, sent, npmrc));
+        }
+    }
+    async #download(tarball, url, npmrc, urlOrigin) {
+        const auth = resolveAuthHeader(npmrc.config, url, tarball.name, this.#env);
+        const sent = this.#sentCredentials(url, urlOrigin, auth);
+        // A redirect can make the credentials moot: follow-redirects drops
+        // confidential headers rather than hand them to another host, so
+        // whatever answered never saw them and "they were rejected" would be
+        // wrong. Tarball downloads redirect to CDNs routinely.
+        //
+        // Observed, not predicted: the drop happens before `beforeRedirect`
+        // runs and mutates the very options handed to it, so the hook can see
+        // what actually survived. Re-deriving the library's rule would get
+        // subdomain redirects (which keep the header) and protocol downgrades
+        // (which drop it regardless of host) wrong, and would rot silently if
+        // the policy ever changed.
+        //
+        // The hop itself is recorded even when nothing was sent: whatever
+        // answered is then not the host the reader configured, and telling them
+        // to add credentials for a host that never asked is its own dead end.
+        const redirect = {};
         try {
             const response = await axios.get(url, assignProxy(url, {
                 responseType: 'arraybuffer',
@@ -293,7 +636,23 @@ export class EmbeddedPackagesMaterializer {
                     // otherwise make axios gunzip it, breaking integrity verification
                     // with a misleading "different artifact" error.
                     'accept-encoding': 'identity',
-                    ...(authHeader !== undefined ? { authorization: authHeader } : {}),
+                    ...(auth !== undefined ? { authorization: auth.header } : {}),
+                },
+                beforeRedirect: (options) => {
+                    redirect.host = options.host;
+                    if (sent === undefined) {
+                        return;
+                    }
+                    const keptHeader = Object.keys(options.headers ?? {})
+                        .some(header => header.toLowerCase() === 'authorization');
+                    // `!= null` rather than `!== undefined`: the legacy URL path
+                    // yields `null` here, and treating that as "credentials survived"
+                    // would fail open on the very check meant to catch a drop.
+                    const keptUrlAuth = options.auth != null && options.auth !== '';
+                    // Assigned rather than latched: a later hop back to the original
+                    // origin restores URL credentials, and reporting them as dropped
+                    // would send the reader to inspect the wrong host.
+                    redirect.credentialsDropped = !keptHeader && !keptUrlAuth;
                 },
                 timeout: DOWNLOAD_TIMEOUT_MS,
                 maxContentLength: MAX_TARBALL_BYTES,
@@ -301,13 +660,8 @@ export class EmbeddedPackagesMaterializer {
             return Buffer.from(response.data);
         }
         catch (err) {
-            const status = err?.response?.status;
-            const statusHint = status !== undefined ? ` (HTTP ${status})` : '';
-            const authHint = status === 401 || status === 403
-                ? ` Check that your .npmrc contains valid credentials for this registry.`
-                : '';
-            throw new EmbeddedPackageError(`Failed to download embedded package '${tarball.name}@${tarball.version}'`
-                + ` from '${redactUrl(url)}'${statusHint}.${authHint}`, { cause: err });
+            throw registryHttpError(err, `Failed to download embedded package '${tarball.name}@${tarball.version}'`
+                + ` from '${redactUrl(url)}'`, status => downloadFailureHint(status, sent, npmrc, redirect));
         }
     }
 }