@pnpm/resolving.npm-resolver 1102.1.7 → 1102.1.9

package/lib/fetch.d.ts

@@ -0,0 +1,45 @@
+import { FetchError, type FetchErrorRequest, type FetchErrorResponse, PnpmError } from '@pnpm/error';
+import type { FetchFromRegistry, RetryTimeoutOptions } from '@pnpm/fetching.types';
+import type { PackageMeta } from '@pnpm/resolving.registry.types';
+export interface FetchMetadataResult {
+    meta: PackageMeta;
+    /**
+     * The raw registry response body, used only to mirror the response to disk
+     * without re-serializing `meta`. A fresh fetch always sets it, and every
+     * caller sharing that in-flight request sees it. Once the request settles
+     * the phase-long memo cache drops the body (see memoizeFetchMetadata.ts),
+     * so later cache hits see `undefined` and the cache never pins the body.
+     */
+    jsonText: string | undefined;
+    etag?: string;
+    notModified?: false;
+}
+export interface FetchMetadataNotModifiedResult {
+    notModified: true;
+}
+export declare class RegistryResponseError extends FetchError {
+    readonly pkgName: string;
+    constructor(request: FetchErrorRequest, response: FetchErrorResponse, pkgName: string);
+}
+export interface FetchMetadataFromFromRegistryOptions {
+    fetch: FetchFromRegistry;
+    retry: RetryTimeoutOptions;
+    timeout: number;
+    fetchWarnTimeoutMs: number;
+}
+export interface FetchMetadataOptions {
+    registry: string;
+    authHeaderValue?: string;
+    cacheBypass?: boolean;
+    fullMetadata?: boolean;
+    etag?: string;
+    modified?: string;
+}
+export declare function fetchMetadataFromFromRegistry(fetchOpts: FetchMetadataFromFromRegistryOptions, pkgName: string, { authHeaderValue, cacheBypass, etag: cachedEtag, fullMetadata, modified: cachedModified, registry, }: FetchMetadataOptions): Promise<FetchMetadataResult | FetchMetadataNotModifiedResult>;
+/**
+ * A 304 answers a validator with "the body you already have is current". Sent
+ * without one — either because nothing was cached or because `cacheBypass`
+ * dropped the validators to recover a lost cache entry — it refers to a body
+ * nobody holds, so there is nothing to serve and nothing left to retry.
+ */
+export declare function notModifiedWithoutCacheError(pkgName: string): PnpmError;

package/lib/fetch.js

@@ -0,0 +1,237 @@
+import url from 'node:url';
+import util from 'node:util';
+import { requestRetryLogger } from '@pnpm/core-loggers';
+import { FetchError, PnpmError, redactUrlCredentials, } from '@pnpm/error';
+import { globalWarn } from '@pnpm/logger';
+import * as retry from '@zkochan/retry';
+import semver from 'semver';
+import { clearMeta } from './clearMeta.js';
+/**
+ * Content type of an abbreviated (install-oriented) package metadata document.
+ * A spec-compliant registry echoes this in the response `Content-Type` when it
+ * honors the abbreviated `Accept` header. Its absence signals that the registry
+ * ignored the header and served the full document instead.
+ * https://github.com/npm/registry/blob/main/docs/responses/package-metadata.md
+ */
+const ABBREVIATED_META_CONTENT_TYPE = 'application/vnd.npm.install-v1+json';
+export class RegistryResponseError extends FetchError {
+    pkgName;
+    constructor(request, response, pkgName) {
+        let hint;
+        if (response.status === 404) {
+            hint = `${pkgName} is not in the npm registry, or you have no permission to fetch it.`;
+            const nameWithoutVersion = stripTrailingSemverSuffix(pkgName);
+            if (nameWithoutVersion != null) {
+                hint += ` Did you mean ${nameWithoutVersion}?`;
+            }
+        }
+        super(request, response, hint);
+        this.pkgName = pkgName;
+    }
+}
+/**
+ * Detect when a package name accidentally includes a `<version>` suffix
+ * (e.g. `lodash@4.17.21` or `lodash4.17.21`) and return the part before the
+ * version. Returns `undefined` when no semver suffix is present.
+ *
+ * Implemented as an O(n) scan to avoid polynomial backtracking on adversarial
+ * input (CodeQL: js/polynomial-redos).
+ */
+function stripTrailingSemverSuffix(pkgName) {
+    // Common case: "name@version" – split on the rightmost '@'.
+    // `atIdx > 0` rules out the leading '@' of scoped names like '@scope/foo'.
+    const atIdx = pkgName.lastIndexOf('@');
+    if (atIdx > 0 && semver.valid(pkgName.slice(atIdx + 1)) != null) {
+        return pkgName.slice(0, atIdx);
+    }
+    // Fallback: detect a trailing "<digits>.<digits>.<digits>" appended to a name
+    // with no separator (e.g. "foo1.0.0"). We walk backwards through three
+    // digit-blocks separated by dots; this is O(n) and free of regex backtracking.
+    let i = pkgName.length;
+    i = consumeTrailingDigits(pkgName, i);
+    if (i === pkgName.length || i === 0 || pkgName.charCodeAt(i - 1) !== 46 /* '.' */)
+        return undefined;
+    i--;
+    const beforePatch = i;
+    i = consumeTrailingDigits(pkgName, i);
+    if (i === beforePatch || i === 0 || pkgName.charCodeAt(i - 1) !== 46)
+        return undefined;
+    i--;
+    const beforeMinor = i;
+    i = consumeTrailingDigits(pkgName, i);
+    if (i === beforeMinor || i === 0)
+        return undefined;
+    if (semver.valid(pkgName.slice(i)) == null)
+        return undefined;
+    let prefix = pkgName.slice(0, i);
+    if (prefix.endsWith('@'))
+        prefix = prefix.slice(0, -1);
+    return prefix.length > 0 ? prefix : undefined;
+}
+function consumeTrailingDigits(s, end) {
+    let i = end;
+    while (i > 0) {
+        const c = s.charCodeAt(i - 1);
+        if (c < 48 || c > 57)
+            break;
+        i--;
+    }
+    return i;
+}
+export async function fetchMetadataFromFromRegistry(fetchOpts, pkgName, { authHeaderValue, cacheBypass = false, etag: cachedEtag, fullMetadata, modified: cachedModified, registry, }) {
+    const uri = toUri(pkgName, registry);
+    const op = retry.operation(fetchOpts.retry);
+    const ifNoneMatch = cacheBypass ? undefined : cachedEtag;
+    const ifModifiedSince = cacheBypass || !cachedModified
+        ? undefined
+        : new Date(cachedModified).toUTCString();
+    const hasValidator = Boolean(ifNoneMatch || ifModifiedSince);
+    return new Promise((resolve, reject) => {
+        op.attempt(async (attempt) => {
+            let response;
+            const startTime = Date.now();
+            try {
+                const requestOptions = {
+                    authHeaderValue,
+                    compress: true,
+                    fullMetadata,
+                    ifNoneMatch,
+                    ifModifiedSince,
+                    retry: fetchOpts.retry,
+                    timeout: fetchOpts.timeout,
+                    headers: cacheBypass ? { 'cache-control': 'no-cache' } : undefined,
+                };
+                response = await fetchOpts.fetch(uri, requestOptions);
+                if (response.status === 304 && !hasValidator && !cacheBypass) {
+                    response = await fetchOpts.fetch(uri, {
+                        ...requestOptions,
+                        headers: {
+                            'cache-control': 'no-cache',
+                        },
+                    });
+                }
+            }
+            catch (error) { // eslint-disable-line
+                // Redact credentials embedded in the URL from the cause as well, not
+                // just the top-level message: a reporter or debugger that renders
+                // `error.cause` would otherwise print the raw URL-bearing message. The
+                // `stack` string embeds the original (pre-mutation) message, so redact
+                // it too — mutating `message` alone leaves the credentials in `stack`.
+                if (util.types.isNativeError(error)) {
+                    if (typeof error.message === 'string')
+                        error.message = redactUrlCredentials(error.message);
+                    if (typeof error.stack === 'string')
+                        error.stack = redactUrlCredentials(error.stack);
+                }
+                reject(new PnpmError('META_FETCH_FAIL', redactUrlCredentials(`GET ${uri}: ${error.message}`), { attempts: attempt, cause: error }));
+                return;
+            }
+            if (response.status === 304) {
+                if (!hasValidator) {
+                    reject(notModifiedWithoutCacheError(pkgName));
+                    return;
+                }
+                resolve({ notModified: true });
+                return;
+            }
+            if (response.status >= 400) {
+                const request = {
+                    authHeaderValue,
+                    url: uri,
+                };
+                reject(new RegistryResponseError(request, response, pkgName));
+                return;
+            }
+            // Here we only retry broken JSON responses.
+            // Other HTTP issues are retried by the @pnpm/network.fetch library
+            try {
+                const jsonText = await response.text();
+                const meta = JSON.parse(jsonText);
+                // Check if request took longer than expected
+                const elapsedMs = Date.now() - startTime;
+                if (elapsedMs > fetchOpts.fetchWarnTimeoutMs) {
+                    globalWarn(`Request took ${elapsedMs}ms: ${uri}`);
+                }
+                resolve({
+                    ...normalizeAbbreviatedResponse({ fullMetadata, meta, jsonText, response }),
+                    etag: response.headers.get('etag') ?? undefined,
+                });
+            }
+            catch (error) { // eslint-disable-line
+                const timeout = op.retry(new PnpmError('BROKEN_METADATA_JSON', error.message));
+                if (timeout === false) {
+                    reject(op.mainError());
+                    return;
+                }
+                // Extract error properties into a plain object because Error properties
+                // are non-enumerable and don't serialize well through the logging system
+                const errorInfo = {
+                    name: error.name,
+                    message: error.message,
+                    code: error.code,
+                    errno: error.errno,
+                };
+                requestRetryLogger.debug({
+                    attempt,
+                    error: errorInfo,
+                    maxRetries: fetchOpts.retry.retries,
+                    method: 'GET',
+                    timeout,
+                    url: uri,
+                });
+            }
+        });
+    });
+}
+/**
+ * A 304 answers a validator with "the body you already have is current". Sent
+ * without one — either because nothing was cached or because `cacheBypass`
+ * dropped the validators to recover a lost cache entry — it refers to a body
+ * nobody holds, so there is nothing to serve and nothing left to retry.
+ */
+export function notModifiedWithoutCacheError(pkgName) {
+    return new PnpmError('META_NOT_MODIFIED_WITHOUT_CACHE', `Registry returned 304 for ${pkgName} without an existing cache to refresh.`);
+}
+/**
+ * When the resolver asked for abbreviated metadata but the registry ignored the
+ * `Accept` header and returned the full document (detected via the response
+ * `Content-Type`), strip it down to the abbreviated field set so downstream
+ * consumers — the in-memory cache, the on-disk mirror, and the resolver — never
+ * carry the megabytes of install-irrelevant data (scripts, exports, readme,
+ * custom fields) that a full document contains.
+ *
+ * Registries that honor the header (e.g. the npm registry) echo the abbreviated
+ * `Content-Type`, so this is a no-op for them: no re-serialization, no field
+ * stripping — the happy path pays nothing.
+ */
+function normalizeAbbreviatedResponse({ fullMetadata, meta, jsonText, response }) {
+    if (fullMetadata)
+        return { meta, jsonText };
+    if (parseMediaType(response.headers.get('content-type')) === ABBREVIATED_META_CONTENT_TYPE)
+        return { meta, jsonText };
+    const normalized = clearMeta(meta);
+    return { meta: normalized, jsonText: JSON.stringify(normalized) };
+}
+/**
+ * Extracts the media type from a `Content-Type` header value, dropping
+ * parameters such as `; charset=utf-8`. Media types are case-insensitive
+ * (RFC 9110 §8.3.1), so the result is lowercased for comparison.
+ */
+function parseMediaType(contentType) {
+    if (contentType == null)
+        return undefined;
+    const semicolonIndex = contentType.indexOf(';');
+    const mediaType = semicolonIndex === -1 ? contentType : contentType.slice(0, semicolonIndex);
+    return mediaType.trim().toLowerCase();
+}
+function toUri(pkgName, registry) {
+    let encodedName;
+    if (pkgName[0] === '@') {
+        encodedName = `@${encodeURIComponent(pkgName.slice(1))}`;
+    }
+    else {
+        encodedName = encodeURIComponent(pkgName);
+    }
+    return new url.URL(encodedName, registry.endsWith('/') ? registry : `${registry}/`).toString();
+}
+//# sourceMappingURL=fetch.js.map

package/lib/fetchAttestationPublishedAt.d.ts

@@ -0,0 +1,31 @@
+import type { FetchMetadataFromFromRegistryOptions } from './fetch.js';
+/**
+ * Per-version publish timestamp from npm's attestation endpoint —
+ * `/-/npm/v1/attestations/<name>@<version>`.
+ *
+ * The response is a small JSON document containing one or more Sigstore
+ * bundles. We read `bundle.verificationMaterial.tlogEntries[].integratedTime`
+ * (the Rekor inclusion time) and surface it as an ISO date. This is a
+ * couple of seconds after the actual publish — close enough for a
+ * release-age policy that operates in minutes/hours/days.
+ *
+ * We deliberately do **not** verify the Sigstore signature here: the
+ * trust model is identical to reading the registry's `time` field on
+ * the full metadata document. The win is bandwidth — the attestation
+ * payload is tens of KB versus the multi-MB full metadata document, so
+ * cold-cache + `--frozen-lockfile` installs against a fleet of
+ * provenance-published packages pay far less to verify timestamps.
+ *
+ * Returns `undefined` when:
+ *
+ * - The package has no published attestations (`404`).
+ * - The response is malformed or missing the timestamp.
+ * - The request itself fails (network error, registry 5xx).
+ *
+ * In all of those cases the caller falls back to fetching full metadata.
+ */
+export interface FetchAttestationOptions {
+    registry: string;
+    authHeaderValue?: string;
+}
+export declare function fetchAttestationPublishedAt(fetchOpts: FetchMetadataFromFromRegistryOptions, pkgName: string, version: string, opts: FetchAttestationOptions): Promise<string | undefined>;

package/lib/fetchAttestationPublishedAt.js

@@ -0,0 +1,99 @@
+import * as retry from '@zkochan/retry';
+export async function fetchAttestationPublishedAt(fetchOpts, pkgName, version, opts) {
+    const url = `${opts.registry.replace(/\/$/, '')}/-/npm/v1/attestations/${pkgName}@${version}`;
+    const retryOperation = retry.operation(fetchOpts.retry);
+    return new Promise((resolve) => {
+        retryOperation.attempt(async () => {
+            let response;
+            try {
+                response = await fetchOpts.fetch(url, {
+                    authHeaderValue: opts.authHeaderValue,
+                    retry: fetchOpts.retry,
+                    timeout: fetchOpts.timeout,
+                });
+            }
+            catch {
+                // Network errors fall through to the full-metadata path; the
+                // caller's `fetchFullMetadataCached` has its own retry policy.
+                resolve(undefined);
+                return;
+            }
+            // 404 = package never published attestations. Other 4xx/5xx also
+            // mean "can't get an answer from this endpoint, fall back."
+            if (response.status >= 400) {
+                resolve(undefined);
+                return;
+            }
+            let body;
+            try {
+                body = await response.json();
+            }
+            catch {
+                resolve(undefined);
+                return;
+            }
+            resolve(extractPublishedAt(body));
+        });
+    });
+}
+/**
+ * Pull the earliest `integratedTime` across every attestation bundle in
+ * the response and convert it to an ISO timestamp. Earliest is the
+ * conservative choice: if two attestations disagree (e.g. publish
+ * v0.1 vs SLSA provenance v1), we attribute the publish to the older
+ * Rekor entry. The Rekor timestamp is what tells us when the artifact
+ * existed in a transparency log — that's the floor on publish time.
+ */
+function extractPublishedAt(body) {
+    if (!body || typeof body !== 'object')
+        return undefined;
+    const attestations = body.attestations;
+    if (!Array.isArray(attestations))
+        return undefined;
+    let earliestSeconds;
+    for (const attestation of attestations) {
+        const seconds = readEarliestIntegratedTime(attestation);
+        if (seconds == null)
+            continue;
+        if (earliestSeconds == null || seconds < earliestSeconds) {
+            earliestSeconds = seconds;
+        }
+    }
+    if (earliestSeconds == null)
+        return undefined;
+    return new Date(earliestSeconds * 1000).toISOString();
+}
+function readEarliestIntegratedTime(attestation) {
+    if (!attestation || typeof attestation !== 'object')
+        return undefined;
+    const bundle = attestation.bundle;
+    if (!bundle || typeof bundle !== 'object')
+        return undefined;
+    const verificationMaterial = bundle.verificationMaterial;
+    if (!verificationMaterial || typeof verificationMaterial !== 'object')
+        return undefined;
+    const tlogEntries = verificationMaterial.tlogEntries;
+    if (!Array.isArray(tlogEntries))
+        return undefined;
+    let earliest;
+    for (const entry of tlogEntries) {
+        if (!entry || typeof entry !== 'object')
+            continue;
+        const rawIntegratedTime = entry.integratedTime;
+        // npm serializes integratedTime as a string ("1778583836") to avoid
+        // JSON precision loss; accept either string or number defensively.
+        const seconds = parseIntegratedTimeSeconds(rawIntegratedTime);
+        if (seconds == null)
+            continue;
+        if (earliest == null || seconds < earliest)
+            earliest = seconds;
+    }
+    return earliest;
+}
+function parseIntegratedTimeSeconds(raw) {
+    const seconds = typeof raw === 'string' ? Number(raw) : typeof raw === 'number' ? raw : NaN;
+    if (!Number.isFinite(seconds) || seconds <= 0)
+        return undefined;
+    return seconds;
+}
+//# sourceMappingURL=fetchAttestationPublishedAt.js.map

package/lib/fetchFullMetadataCached.d.ts

@@ -0,0 +1,33 @@
+import type { PackageMeta } from '@pnpm/resolving.registry.types';
+import { type FetchMetadataFromFromRegistryOptions } from './fetch.js';
+export interface FetchMetadataCachedOptions {
+    registry: string;
+    authHeaderValue?: string;
+    /**
+     * pnpm's on-disk cache directory. When set, the call issues a conditional
+     * GET against the matching mirror the resolver populates: a 304 Not
+     * Modified response serves the body from disk, a 200 writes the new body
+     * back. Omit to disable caching — every call re-fetches.
+     */
+    cacheDir?: string;
+}
+export type FetchFullMetadataCachedOptions = FetchMetadataCachedOptions;
+/**
+ * Fetch a full registry metadata document for `pkgName`, reusing pnpm's
+ * shared on-disk metadata mirror when `cacheDir` is supplied. Built for the
+ * `minimumReleaseAge` lockfile revalidation gate, which needs the `time`
+ * field that abbreviated metadata omits; the cache reuse keeps repeat
+ * installs from re-downloading the same multi-megabyte document for every
+ * locked package.
+ */
+export declare function fetchFullMetadataCached(fetchOpts: FetchMetadataFromFromRegistryOptions, pkgName: string, opts: FetchFullMetadataCachedOptions): Promise<PackageMeta>;
+/**
+ * Sibling of {@link fetchFullMetadataCached} that hits the abbreviated
+ * metadata endpoint (`Accept: application/vnd.npm.install-v1+json`) and
+ * caches under `ABBREVIATED_META_DIR` — the same mirror the resolver
+ * populates by default. Used by the lockfile verification gate as a
+ * cheap upper-bound check: if the package's `modified` field is older
+ * than the policy cutoff, every version in it predates the cutoff and
+ * no per-version timestamp lookup is needed.
+ */
+export declare function fetchAbbreviatedMetadataCached(fetchOpts: FetchMetadataFromFromRegistryOptions, pkgName: string, opts: FetchMetadataCachedOptions): Promise<PackageMeta>;

package/lib/fetchFullMetadataCached.js

@@ -0,0 +1,75 @@
+import { ABBREVIATED_META_DIR, FULL_META_DIR } from '@pnpm/constants';
+import { fetchMetadataFromFromRegistry, } from './fetch.js';
+import { getPkgMirrorPath, loadMeta, loadMetaHeaders, prepareJsonForDisk, saveMeta } from './pickPackage.js';
+/**
+ * Fetch a full registry metadata document for `pkgName`, reusing pnpm's
+ * shared on-disk metadata mirror when `cacheDir` is supplied. Built for the
+ * `minimumReleaseAge` lockfile revalidation gate, which needs the `time`
+ * field that abbreviated metadata omits; the cache reuse keeps repeat
+ * installs from re-downloading the same multi-megabyte document for every
+ * locked package.
+ */
+export async function fetchFullMetadataCached(fetchOpts, pkgName, opts) {
+    return fetchMetadataCached(fetchOpts, pkgName, { ...opts, fullMetadata: true, metaDir: FULL_META_DIR });
+}
+/**
+ * Sibling of {@link fetchFullMetadataCached} that hits the abbreviated
+ * metadata endpoint (`Accept: application/vnd.npm.install-v1+json`) and
+ * caches under `ABBREVIATED_META_DIR` — the same mirror the resolver
+ * populates by default. Used by the lockfile verification gate as a
+ * cheap upper-bound check: if the package's `modified` field is older
+ * than the policy cutoff, every version in it predates the cutoff and
+ * no per-version timestamp lookup is needed.
+ */
+export async function fetchAbbreviatedMetadataCached(fetchOpts, pkgName, opts) {
+    return fetchMetadataCached(fetchOpts, pkgName, { ...opts, fullMetadata: false, metaDir: ABBREVIATED_META_DIR });
+}
+async function fetchMetadataCached(fetchOpts, pkgName, opts) {
+    const pkgMirror = opts.cacheDir != null
+        ? getPkgMirrorPath(opts.cacheDir, opts.metaDir, opts.registry, pkgName)
+        : null;
+    const cacheHeaders = pkgMirror != null ? await loadMetaHeaders(pkgMirror) : null;
+    const conditional = await fetchMetadataFromFromRegistry(fetchOpts, pkgName, {
+        registry: opts.registry,
+        authHeaderValue: opts.authHeaderValue,
+        fullMetadata: opts.fullMetadata,
+        etag: cacheHeaders?.etag,
+        modified: cacheHeaders?.modified,
+    });
+    if (!conditional.notModified)
+        return persistAndReturn(conditional);
+    // A 304 only resolves as `notModified` when a validator was sent, which
+    // requires cache headers loaded from a mirror — so a null mirror here is an
+    // unreachable invariant breach.
+    if (pkgMirror == null)
+        throw new Error(`Unexpected 304 for ${pkgName} without a metadata cache`);
+    const cached = await loadMeta(pkgMirror);
+    if (cached != null)
+        return cached;
+    // The mirror vanished between the headers read and this read (concurrent
+    // store cleanup, antivirus, ...), so the 304 now validates nothing. Ask again
+    // as a cold cache would, which the registry can only answer with a body or an
+    // error — never another 304.
+    const refetched = await fetchMetadataFromFromRegistry(fetchOpts, pkgName, {
+        registry: opts.registry,
+        authHeaderValue: opts.authHeaderValue,
+        cacheBypass: true,
+        fullMetadata: opts.fullMetadata,
+    });
+    // Unreachable narrowing guard: the cache-bypassing request sends no validator,
+    // so fetchMetadataFromFromRegistry rejects a repeated 304 before returning.
+    if (refetched.notModified)
+        throw new Error(`Unexpected 304 for ${pkgName} on a cache-bypassing refetch`);
+    return persistAndReturn(refetched);
+    // Persist a freshly downloaded body so the next install can do a headers-only
+    // conditional GET, then hand its meta back. Fire-and-forget — a cache-write
+    // failure isn't a reason to fail the caller; the next install just won't get
+    // the speedup.
+    function persistAndReturn(fetched) {
+        if (pkgMirror != null) {
+            saveMeta(pkgMirror, prepareJsonForDisk(fetched.meta, fetched.etag, fetched.jsonText)).catch(() => { });
+        }
+        return fetched.meta;
+    }
+}
+//# sourceMappingURL=fetchFullMetadataCached.js.map

package/lib/index.d.ts

@@ -0,0 +1,133 @@
+import { PnpmError } from '@pnpm/error';
+import type { FetchFromRegistry, GetAuthHeader, RetryTimeoutOptions } from '@pnpm/fetching.types';
+import type { PackageMeta } from '@pnpm/resolving.registry.types';
+import type { DirectoryResolution, LatestInfo, LatestQuery, PkgResolutionId, PreferredVersions, ResolveOptions, ResolveResult, TarballResolution, WantedDependency, WorkspacePackages } from '@pnpm/resolving.resolver-base';
+import type { DependencyManifest, PackageVersionPolicy, PinnedVersion, Registries, TrustPolicy } from '@pnpm/types';
+import { fetchMetadataFromFromRegistry, type FetchMetadataFromFromRegistryOptions, RegistryResponseError } from './fetch.js';
+import { BUILTIN_NAMED_REGISTRIES, parseBareSpecifier, type RegistryPackageSpec } from './parseBareSpecifier.js';
+import { type PackageMetaCache, pickPackage, type PickPackageOptions } from './pickPackage.js';
+import { pickPackageFromMeta, pickVersionByVersionRange } from './pickPackageFromMeta.js';
+import { workspacePrefToNpm } from './workspacePrefToNpm.js';
+export interface NoMatchingVersionErrorOptions {
+    wantedDependency: WantedDependency;
+    packageMeta: PackageMeta;
+    registry: string;
+}
+export declare class NoMatchingVersionError extends PnpmError {
+    readonly packageMeta: PackageMeta;
+    constructor(opts: NoMatchingVersionErrorOptions);
+}
+export declare function formatTimeAgo(date: Date): string | null;
+export { BUILTIN_NAMED_REGISTRIES, fetchMetadataFromFromRegistry, type FetchMetadataFromFromRegistryOptions, type PackageMeta, type PackageMetaCache, parseBareSpecifier, pickPackageFromMeta, pickVersionByVersionRange, type RegistryPackageSpec, RegistryResponseError, workspacePrefToNpm, };
+export { createNpmResolutionVerifier, type CreateNpmResolutionVerifierOptions } from './createNpmResolutionVerifier.js';
+export { MINIMUM_RELEASE_AGE_VIOLATION_CODE, TRUST_DOWNGRADE_VIOLATION_CODE, } from './violationCodes.js';
+export { whichVersionIsPinned } from './whichVersionIsPinned.js';
+export interface ResolverFactoryOptions {
+    cacheDir: string;
+    storeDir?: string;
+    frozenStore?: boolean;
+    fullMetadata?: boolean;
+    filterMetadata?: boolean;
+    offline?: boolean;
+    preferOffline?: boolean;
+    retry?: RetryTimeoutOptions;
+    timeout?: number;
+    registries: Registries;
+    namedRegistries?: Record<string, string>;
+    saveWorkspaceProtocol?: boolean | 'rolling';
+    preserveAbsolutePaths?: boolean;
+    ignoreMissingTimeField?: boolean;
+    fetchWarnTimeoutMs?: number;
+    /** Pre-populated metadata cache. When provided, the resolver uses this
+     *  instead of creating a new LRU cache. Useful for servers that keep
+     *  metadata in SQLite or persist it across requests. */
+    metaCache?: PackageMetaCache;
+}
+export interface NpmResolveResult extends ResolveResult {
+    latest?: string;
+    manifest: DependencyManifest;
+    resolution: TarballResolution;
+    resolvedVia: 'npm-registry';
+}
+export interface JsrResolveResult extends ResolveResult {
+    alias: string;
+    manifest: DependencyManifest;
+    resolution: TarballResolution;
+    resolvedVia: 'jsr-registry';
+}
+export interface NamedRegistryResolveResult extends ResolveResult {
+    alias: string;
+    /** The named-registry alias that was matched, e.g. `gh` or a user-defined name. */
+    registryName: string;
+    manifest: DependencyManifest;
+    resolution: TarballResolution;
+    resolvedVia: 'named-registry';
+}
+export interface WorkspaceResolveResult extends ResolveResult {
+    manifest: DependencyManifest;
+    resolution: DirectoryResolution;
+    resolvedVia: 'workspace';
+}
+export type NpmResolver = (wantedDependency: WantedDependency & {
+    optional?: boolean;
+}, opts: ResolveFromNpmOptions) => Promise<NpmResolveResult | JsrResolveResult | NamedRegistryResolveResult | WorkspaceResolveResult | null>;
+export type ResolveLatestFromNpmStyle = (query: LatestQuery, opts: ResolveOptions) => Promise<LatestInfo | undefined>;
+export declare function createNpmResolver(fetchFromRegistry: FetchFromRegistry, getAuthHeader: GetAuthHeader, opts: ResolverFactoryOptions): {
+    resolveFromNpm: NpmResolver;
+    resolveFromJsr: NpmResolver;
+    resolveFromNamedRegistry: NpmResolver;
+    resolveLatestFromNpm: ResolveLatestFromNpmStyle;
+    resolveLatestFromJsr: ResolveLatestFromNpmStyle;
+    resolveLatestFromNamedRegistry: ResolveLatestFromNpmStyle;
+    clearCache: () => void;
+};
+export interface ResolveFromNpmContext {
+    pickPackage: (spec: RegistryPackageSpec, opts: PickPackageOptions) => ReturnType<typeof pickPackage>;
+    getAuthHeaderValueByURI: GetAuthHeader;
+    registries: Registries;
+    namedRegistries: Record<string, string>;
+    namedRegistryNames: ReadonlySet<string>;
+    saveWorkspaceProtocol?: boolean | 'rolling';
+    peekManifestFromStore?: (opts: {
+        id: PkgResolutionId;
+        integrity: string;
+        name?: string;
+        version?: string;
+    }) => Promise<DependencyManifest | undefined>;
+    /** Deduplicates the held-back-update warning per `(name, picked, preferred)`. */
+    warnedHeldBackUpdates: Set<string>;
+}
+export type ResolveFromNpmOptions = {
+    alwaysTryWorkspacePackages?: boolean;
+    defaultTag?: string;
+    publishedBy?: Date;
+    publishedByExclude?: PackageVersionPolicy;
+    pickLowestVersion?: boolean;
+    trustPolicy?: TrustPolicy;
+    trustPolicyExclude?: PackageVersionPolicy;
+    trustPolicyIgnoreAfter?: number;
+    dryRun?: boolean;
+    lockfileDir?: string;
+    preferredVersions?: PreferredVersions;
+    preferWorkspacePackages?: boolean;
+    update?: false | 'compatible' | 'latest';
+    updateRequested?: boolean;
+    updateChecksums?: boolean;
+    injectWorkspacePackages?: boolean;
+    calcSpecifier?: boolean;
+    pinnedVersion?: PinnedVersion;
+} & ({
+    projectDir?: string;
+    workspacePackages?: undefined;
+} | {
+    projectDir: string;
+    workspacePackages: WorkspacePackages;
+});
+/**
+ * Construct the LRU `PackageMetaCache` instance the resolver uses by
+ * default. Exported so the install layer can build one cache and hand
+ * the same reference to both the resolver and the verifier — the
+ * verifier's fast path reads from it when the resolver has already
+ * fetched a packument during the same install.
+ */
+export declare function createDefaultPackageMetaCache(): PackageMetaCache;