@pnpm/resolving.npm-resolver 1101.1.1 → 1101.3.0

package/lib/createNpmResolutionVerifier.d.ts

@@ -0,0 +1,74 @@
+import type { ResolutionVerifier } from '@pnpm/resolving.resolver-base';
+import type { Registries, TrustPolicy } from '@pnpm/types';
+import type { FetchMetadataFromFromRegistryOptions } from './fetch.js';
+import { type FetchFullMetadataCachedOptions } from './fetchFullMetadataCached.js';
+export interface CreateNpmResolutionVerifierOptions {
+    /**
+     * Minimum age (in minutes) a published version must reach before it is
+     * accepted. When unset, the verifier is a no-op for the age check.
+     */
+    minimumReleaseAge?: number;
+    /**
+     * Retained on the options bag because the resolver path branches on it
+     * (the lowest-version fallback) and tests forward both fields together.
+     * The verifier itself no longer gates on this flag — once the loose-mode
+     * auto-collect makes every accepted-immature pin explicit in
+     * `minimumReleaseAgeExclude`, running the verifier in loose mode is the
+     * thing that proves the manifest stays in sync with the lockfile.
+     */
+    minimumReleaseAgeStrict?: boolean;
+    minimumReleaseAgeExclude?: string[];
+    /**
+     * When the registry's metadata lacks the per-version `time` field
+     * (some self-hosted registries strip it), the verifier can't apply
+     * the maturity cutoff. Set this to `true` to mirror the resolver's
+     * `pickMatchingVersionFinal` warn-and-skip behavior — the verifier
+     * passes the entry with a one-time `globalWarn`, instead of failing
+     * closed. Defaults to `false` so the verifier stays stricter than
+     * the resolver only when the user has explicitly opted in to the
+     * skip on the resolver side.
+     */
+    ignoreMissingTimeField?: boolean;
+    /**
+     * `'no-downgrade'` rejects a lockfile entry whose version has weaker
+     * trust evidence (no attestations) than an earlier-published version
+     * had. This mirrors the resolver-time `failIfTrustDowngraded` check
+     * applied during fresh resolution — the verifier catches the same
+     * supply-chain signal on entries that bypassed resolution (peek-path,
+     * frozen lockfile, etc.).
+     */
+    trustPolicy?: TrustPolicy;
+    trustPolicyExclude?: string[];
+    trustPolicyIgnoreAfter?: number;
+    registries: Registries;
+    /**
+     * Registries reached via the named-registry resolver chain (e.g. `gh:` →
+     * GitHub Packages). When a lockfile entry's tarball URL falls under one of
+     * these registry base URLs, route the manifest fetch there instead of the
+     * scope-derived default.
+     */
+    namedRegistries?: Record<string, string>;
+    /**
+     * Cache-aware full-metadata fetcher. Decoupled from the resolver pipeline
+     * so abbreviated metadata and `peekManifestFromStore` fast paths cannot
+     * hide the publish timestamp.
+     */
+    fetchOpts: FetchMetadataFromFromRegistryOptions;
+    getAuthHeaderValueByURI: (registry: string) => string | undefined;
+    cacheDir?: FetchFullMetadataCachedOptions['cacheDir'];
+    /** Overrides Date.now() for tests. */
+    now?: number;
+}
+/**
+ * Returns a `ResolutionVerifier` that re-applies the `minimumReleaseAge`
+ * and/or `trustPolicy='no-downgrade'` policies to npm-registry-resolved
+ * lockfile entries, or `undefined` when no policy is active. Pairs with
+ * `createNpmResolver`: each resolver factory may export a sibling
+ * verifier factory that the default-resolver combines.
+ *
+ * Designed for fail-closed semantics: if the manifest can't be loaded or
+ * the pinned version is missing from it, the verifier reports a violation
+ * rather than silently passing. Mirrors the post-resolution gate bun added
+ * for the same shape of bug in oven-sh/bun#30526.
+ */
+export declare function createNpmResolutionVerifier(opts: CreateNpmResolutionVerifierOptions): ResolutionVerifier | undefined;

package/lib/createNpmResolutionVerifier.js

@@ -0,0 +1,473 @@
+import { pickRegistryForPackage } from '@pnpm/config.pick-registry-for-package';
+import { createPackageVersionPolicy } from '@pnpm/config.version-policy';
+import { FULL_META_DIR } from '@pnpm/constants';
+import { PnpmError } from '@pnpm/error';
+import semver from 'semver';
+import { fetchAttestationPublishedAt } from './fetchAttestationPublishedAt.js';
+import { fetchAbbreviatedMetadataCached, fetchFullMetadataCached, } from './fetchFullMetadataCached.js';
+import { BUILTIN_NAMED_REGISTRIES } from './parseBareSpecifier.js';
+import { getPkgMirrorPath, loadMeta, warnMissingTimeFieldOnce } from './pickPackage.js';
+import { failIfTrustDowngraded } from './trustChecks.js';
+import { MINIMUM_RELEASE_AGE_VIOLATION_CODE, TRUST_DOWNGRADE_VIOLATION_CODE, } from './violationCodes.js';
+/**
+ * Returns a `ResolutionVerifier` that re-applies the `minimumReleaseAge`
+ * and/or `trustPolicy='no-downgrade'` policies to npm-registry-resolved
+ * lockfile entries, or `undefined` when no policy is active. Pairs with
+ * `createNpmResolver`: each resolver factory may export a sibling
+ * verifier factory that the default-resolver combines.
+ *
+ * Designed for fail-closed semantics: if the manifest can't be loaded or
+ * the pinned version is missing from it, the verifier reports a violation
+ * rather than silently passing. Mirrors the post-resolution gate bun added
+ * for the same shape of bug in oven-sh/bun#30526.
+ */
+export function createNpmResolutionVerifier(opts) {
+    const ageCheckActive = Boolean(opts.minimumReleaseAge);
+    const trustCheckActive = opts.trustPolicy === 'no-downgrade';
+    // No policy → no verifier. Skipping early keeps the install-side fan-out
+    // empty when nothing is configured.
+    if (!ageCheckActive && !trustCheckActive)
+        return undefined;
+    const cutoff = ageCheckActive
+        ? (opts.now ?? Date.now()) - opts.minimumReleaseAge * 60 * 1000
+        : 0;
+    const excludePolicy = opts.minimumReleaseAgeExclude?.length
+        ? createExcludePolicy(opts.minimumReleaseAgeExclude, 'minimumReleaseAgeExclude')
+        : undefined;
+    const trustExcludePolicy = opts.trustPolicyExclude?.length
+        ? createExcludePolicy(opts.trustPolicyExclude, 'trustPolicyExclude')
+        : undefined;
+    // Pre-normalize named-registry URLs and sort by length so two registries
+    // that share a hostname but differ by path (e.g. `https://npm/team-a/` vs
+    // `https://npm/team-b/`) route to the longest matching prefix — matching
+    // only `origin` would silently send lookups to the wrong one. Built-in
+    // aliases (`gh:` → npm.pkg.github.com, etc.) are merged in alongside the
+    // user-defined ones so the verifier recognizes the same set of named
+    // registries the resolver does; otherwise a package resolved via `gh:`
+    // would land in the lockfile with a tarball URL the verifier can't route.
+    const namedRegistryPrefixes = Object.values({
+        ...BUILTIN_NAMED_REGISTRIES,
+        ...(opts.namedRegistries ?? {}),
+    })
+        .map((url) => {
+        const parsed = tryParseUrl(url);
+        if (!parsed)
+            return null;
+        // Ensure trailing slash so prefix matching against tarball URLs (which
+        // always include the package path under the registry root) does not
+        // accidentally match a sibling registry whose URL shares a prefix string.
+        const pathname = parsed.pathname.endsWith('/') ? parsed.pathname : `${parsed.pathname}/`;
+        return `${parsed.origin}${pathname}`;
+    })
+        .filter((value) => value != null)
+        .sort((a, b) => b.length - a.length);
+    // Per-install dedup of every network/disk fetch the verifier issues.
+    // The maturity check uses the layered `fetchPublishedAt` lookup; the
+    // trust check uses an attestation fast-path before falling back to
+    // the same full-metadata mirror. All maps live here so verifying
+    // many versions of the same package only pays the disk/network costs
+    // once. The on-disk conditional-GET cache is handled inside
+    // fetch{Abbreviated,Full}MetadataCached via the resolver's shared
+    // mirrors at opts.cacheDir.
+    const lookupContext = {
+        fetchOpts: opts.fetchOpts,
+        getAuthHeaderValueByURI: opts.getAuthHeaderValueByURI,
+        cacheDir: opts.cacheDir,
+        cutoffMs: cutoff,
+        abbreviatedMetaCache: new Map(),
+        publishedAtCache: new Map(),
+        localMetaCache: new Map(),
+        fullMetaCache: new Map(),
+        fullMetaForTrustCache: new Map(),
+    };
+    const minimumReleaseAge = opts.minimumReleaseAge ?? 0;
+    const trustPolicy = opts.trustPolicy;
+    const trustPolicyIgnoreAfter = opts.trustPolicyIgnoreAfter;
+    const verify = async (resolution, { name, version }) => {
+        if (!isNpmRegistryResolution(resolution))
+            return { ok: true };
+        // Non-semver versions identify URL tarballs, file: refs, git refs, etc.
+        // Neither the age nor the trust policy applies, and a registry lookup
+        // would 404.
+        if (!semver.valid(version))
+            return { ok: true };
+        const ageApplies = ageCheckActive && !isExcluded(excludePolicy, name, version);
+        const trustApplies = trustCheckActive && !isExcluded(trustExcludePolicy, name, version);
+        if (!ageApplies && !trustApplies)
+            return { ok: true };
+        const tarballUrl = resolution.tarball;
+        const registry = pickRegistryForVersion(opts.registries, namedRegistryPrefixes, name, tarballUrl);
+        if (ageApplies) {
+            const ageViolation = await runAgeCheck(lookupContext, registry, name, version, cutoff, opts.ignoreMissingTimeField === true);
+            if (ageViolation)
+                return ageViolation;
+        }
+        if (trustApplies) {
+            const trustViolation = await runTrustCheck(lookupContext, registry, name, version, {
+                trustPolicyExclude: trustExcludePolicy,
+                trustPolicyIgnoreAfter,
+            });
+            if (trustViolation)
+                return trustViolation;
+        }
+        return { ok: true };
+    };
+    // Snapshot the exclude lists (sorted, deduped) and require an exact
+    // match in `canTrustPastCheck`: cache identity == policy identity.
+    // Any change to either exclude list — adding, removing, or
+    // substituting an entry — invalidates the cached run. This is
+    // stricter than a pure correctness check would require (adding to
+    // either list is more permissive and the cached pass would still
+    // hold), but it makes the cache contract trivial to reason about and
+    // removes a class of bypasses where a previously-approved version
+    // stays trusted after its exclude entry has been pulled.
+    const sortedMinAgeExcludes = [...new Set(opts.minimumReleaseAgeExclude ?? [])].sort();
+    const sortedTrustExcludes = [...new Set(opts.trustPolicyExclude ?? [])].sort();
+    return {
+        verify,
+        policy: {
+            minimumReleaseAge,
+            minimumReleaseAgeExclude: sortedMinAgeExcludes,
+            trustPolicy: trustPolicy ?? null,
+            trustPolicyExclude: sortedTrustExcludes,
+            trustPolicyIgnoreAfter: trustPolicyIgnoreAfter ?? null,
+        },
+        canTrustPastCheck: (cached) => {
+            // Maturity: a previously cached run under a larger cutoff
+            // (stricter window) is trustworthy under a smaller current one —
+            // its set of accepted versions is a subset of today's. The
+            // reverse — tightening the cutoff — invalidates the cached run:
+            // versions that passed before may now be in-window. Non-number
+            // cached values come from an older record shape and aren't trusted.
+            const past = cached.minimumReleaseAge;
+            const pastNumber = typeof past === 'number' ? past : 0;
+            if (pastNumber < minimumReleaseAge)
+                return false;
+            // Excludes: today's sorted-deduped lists must match the cached
+            // ones byte for byte. Older records (no field) fall back to an
+            // empty array, so they only trust today's empty policy.
+            const pastMinAgeExcludes = Array.isArray(cached.minimumReleaseAgeExclude)
+                ? cached.minimumReleaseAgeExclude
+                : [];
+            if (JSON.stringify(pastMinAgeExcludes) !== JSON.stringify(sortedMinAgeExcludes))
+                return false;
+            // Trust policy: any change to `trustPolicy`, the exclude list, or
+            // the ignore-after cutoff invalidates the cached run. Older
+            // records (no trust field at all) treat the trust policy as
+            // absent and are only trusted under an unset-today policy.
+            const pastTrustPolicy = cached.trustPolicy ?? null;
+            const todayTrustPolicy = trustPolicy ?? null;
+            if (pastTrustPolicy !== todayTrustPolicy)
+                return false;
+            const pastTrustExcludes = Array.isArray(cached.trustPolicyExclude)
+                ? cached.trustPolicyExclude
+                : [];
+            if (JSON.stringify(pastTrustExcludes) !== JSON.stringify(sortedTrustExcludes))
+                return false;
+            const pastIgnoreAfter = typeof cached.trustPolicyIgnoreAfter === 'number'
+                ? cached.trustPolicyIgnoreAfter
+                : null;
+            const todayIgnoreAfter = trustPolicyIgnoreAfter ?? null;
+            if (pastIgnoreAfter !== todayIgnoreAfter)
+                return false;
+            return true;
+        },
+    };
+}
+async function runAgeCheck(context, registry, name, version, cutoff, ignoreMissingTimeField) {
+    let published;
+    try {
+        published = await fetchPublishedAt(context, registry, name, version);
+    }
+    catch (err) {
+        return {
+            ok: false,
+            code: MINIMUM_RELEASE_AGE_VIOLATION_CODE,
+            reason: uncheckable('minimumReleaseAge', err instanceof Error ? err.message : String(err)),
+        };
+    }
+    if (!published) {
+        // No source — attestation, local mirror, or full metadata —
+        // surfaced a publish timestamp for this version. The resolver's
+        // pickMatchingVersionFinal honors `minimumReleaseAgeIgnoreMissingTime`
+        // for the same shape (some self-hosted registries strip per-version
+        // `time`); the verifier mirrors that so it can't be stricter than
+        // fresh resolution. Without the flag we still fail closed — better
+        // a false reject than silent bypass when the user hasn't opted in.
+        if (ignoreMissingTimeField) {
+            warnMissingTimeFieldOnce(name);
+            return undefined;
+        }
+        return {
+            ok: false,
+            code: MINIMUM_RELEASE_AGE_VIOLATION_CODE,
+            reason: uncheckable('minimumReleaseAge', 'version not present in registry manifest'),
+        };
+    }
+    const publishedAt = new Date(published);
+    const ts = publishedAt.getTime();
+    if (Number.isNaN(ts)) {
+        return {
+            ok: false,
+            code: MINIMUM_RELEASE_AGE_VIOLATION_CODE,
+            reason: 'publish timestamp is not a valid date',
+        };
+    }
+    if (ts > cutoff) {
+        return {
+            ok: false,
+            code: MINIMUM_RELEASE_AGE_VIOLATION_CODE,
+            reason: `was published at ${publishedAt.toISOString()}, within the minimumReleaseAge cutoff (${new Date(cutoff).toISOString()})`,
+        };
+    }
+    return undefined;
+}
+/**
+ * Run the resolver-time `failIfTrustDowngraded` check against the
+ * pinned lockfile version. The packument is fetched through a
+ * per-install cache so multiple versions of the same package share
+ * one fetch.
+ *
+ * No attestation fast-path here even though the per-version
+ * attestation endpoint is cheaper than the packument: presence of
+ * provenance on the current version is not sufficient to clear a
+ * downgrade. A package could have shipped earlier versions under a
+ * `trustedPublisher` (the higher-rank evidence) and then dropped
+ * back to plain provenance for the version we're verifying —
+ * `failIfTrustDowngraded` correctly flags that, and a "has any
+ * attestation → pass" shortcut would silently miss it.
+ */
+async function runTrustCheck(context, registry, name, version, opts) {
+    let meta;
+    try {
+        meta = await fetchFullMetaForTrust(context, registry, name);
+    }
+    catch (err) {
+        // `fetchFullMetadataCached` rejects (network error, 404, etc.); the
+        // verifier fails closed so a missing manifest can't be mistaken
+        // for a passing trust check.
+        return {
+            ok: false,
+            code: TRUST_DOWNGRADE_VIOLATION_CODE,
+            reason: uncheckable('trustPolicy', err instanceof Error ? err.message : String(err)),
+        };
+    }
+    try {
+        failIfTrustDowngraded(meta, version, opts);
+    }
+    catch (err) {
+        return {
+            ok: false,
+            code: TRUST_DOWNGRADE_VIOLATION_CODE,
+            reason: err instanceof Error ? err.message : String(err),
+        };
+    }
+    return undefined;
+}
+function fetchFullMetaForTrust(context, registry, name) {
+    const cacheKey = `${registry}\x00${name}`;
+    let cachedPromise = context.fullMetaForTrustCache.get(cacheKey);
+    if (cachedPromise == null) {
+        // Don't swallow the fetch rejection here — `runTrustCheck` catches it
+        // and surfaces the underlying message in the violation reason, which
+        // is more actionable than the generic "metadata is unavailable" the
+        // `!meta` fallback emits. The cache still holds the rejected promise
+        // so repeat verifier calls for the same (registry, name) within one
+        // install don't refetch a known-failing endpoint.
+        cachedPromise = fetchFullMetadataCached(context.fetchOpts, name, {
+            registry,
+            authHeaderValue: context.getAuthHeaderValueByURI(registry),
+            cacheDir: context.cacheDir,
+        });
+        context.fullMetaForTrustCache.set(cacheKey, cachedPromise);
+    }
+    return cachedPromise;
+}
+/**
+ * Per-(registry, name, version) lookup with a layered fallback:
+ *
+ * 1. **Abbreviated metadata `modified` shortcut.** This is what the
+ *    resolver already fetches by default; it's a small document with
+ *    a package-level last-modified time but no per-version timestamps.
+ *    If `modified` is older than the policy cutoff, every version in
+ *    this package was published at least that long ago — return the
+ *    `modified` timestamp as a conservative upper bound and skip the
+ *    rest of the chain. Costs one conditional GET that the resolver
+ *    has usually already paid for.
+ * 2. **On-disk full-metadata mirror.** If a previous verification
+ *    populated `FULL_META_DIR`, take the per-version timestamp from
+ *    there.
+ * 3. **npm attestation endpoint.** Small payload, just this version's
+ *    Sigstore-anchored timestamp. Wins on cold cache when the package
+ *    was published with provenance.
+ * 4. **Full metadata fetch.** Last resort — only paid when the
+ *    abbreviated shortcut can't decide, the local full mirror is
+ *    cold, and there's no attestation.
+ */
+async function fetchPublishedAt(context, registry, name, version) {
+    const cacheKey = `${registry}\x00${name}\x00${version}`;
+    let cachedPromise = context.publishedAtCache.get(cacheKey);
+    if (cachedPromise == null) {
+        cachedPromise = resolvePublishedAt(context, registry, name, version);
+        context.publishedAtCache.set(cacheKey, cachedPromise);
+    }
+    return cachedPromise;
+}
+async function resolvePublishedAt(context, registry, name, version) {
+    const abbreviatedShortcut = await tryAbbreviatedModifiedShortcut(context, registry, name, version);
+    if (abbreviatedShortcut != null)
+        return abbreviatedShortcut;
+    const localTime = await readLocalMetaTime(context, registry, name);
+    if (localTime?.[version])
+        return localTime[version];
+    const attestationTime = await fetchAttestationPublishedAt(context.fetchOpts, name, version, {
+        registry,
+        authHeaderValue: context.getAuthHeaderValueByURI(registry),
+    });
+    if (attestationTime != null)
+        return attestationTime;
+    const fullMetaTime = await fetchFullMetaTime(context, registry, name);
+    return fullMetaTime?.[version];
+}
+/**
+ * Returns the abbreviated metadata's `modified` timestamp **iff** it
+ * proves the gate would pass — i.e. modified is strictly older than
+ * the policy cutoff *and* the pinned version still exists in the
+ * package's current versions map.
+ *
+ * The version check is the fail-closed contract: an unpublished or
+ * never-published version must not slip through on the package-level
+ * `modified` timestamp. When the version is missing here we fall
+ * through to the later layers so the caller eventually surfaces the
+ * "version not present in registry manifest" violation.
+ *
+ * Returns `undefined` otherwise (modified is too recent, the metadata
+ * lacks a parseable modified field, the version isn't in the abbreviated
+ * form, or the fetch failed) and the caller proceeds with per-version
+ * lookups.
+ */
+async function tryAbbreviatedModifiedShortcut(context, registry, name, version) {
+    const meta = await fetchAbbreviatedMeta(context, registry, name);
+    const modified = meta?.modified;
+    if (typeof modified !== 'string')
+        return undefined;
+    const modifiedMs = Date.parse(modified);
+    if (Number.isNaN(modifiedMs))
+        return undefined;
+    if (modifiedMs >= context.cutoffMs)
+        return undefined;
+    // The shortcut treats `modified` as an upper bound on every version's
+    // publish time — but only for versions the registry currently lists.
+    // An unpublished or never-published pin would otherwise pass the gate
+    // on a stale package-level timestamp.
+    if (!meta?.versions || !(version in meta.versions))
+        return undefined;
+    return modified;
+}
+function fetchAbbreviatedMeta(context, registry, name) {
+    const cacheKey = `${registry}\x00${name}`;
+    let cachedPromise = context.abbreviatedMetaCache.get(cacheKey);
+    if (cachedPromise == null) {
+        cachedPromise = fetchAbbreviatedMetadataCached(context.fetchOpts, name, {
+            registry,
+            authHeaderValue: context.getAuthHeaderValueByURI(registry),
+            cacheDir: context.cacheDir,
+        }).catch(() => undefined);
+        context.abbreviatedMetaCache.set(cacheKey, cachedPromise);
+    }
+    return cachedPromise;
+}
+function readLocalMetaTime(context, registry, name) {
+    if (!context.cacheDir)
+        return Promise.resolve(undefined);
+    const cacheKey = `${registry}\x00${name}`;
+    let cachedPromise = context.localMetaCache.get(cacheKey);
+    if (cachedPromise == null) {
+        cachedPromise = loadLocalMetaTime(context.cacheDir, registry, name);
+        context.localMetaCache.set(cacheKey, cachedPromise);
+    }
+    return cachedPromise;
+}
+async function loadLocalMetaTime(cacheDir, registry, name) {
+    const pkgMirror = getPkgMirrorPath(cacheDir, FULL_META_DIR, registry, name);
+    const cached = await loadMeta(pkgMirror);
+    return cached?.time;
+}
+function fetchFullMetaTime(context, registry, name) {
+    const cacheKey = `${registry}\x00${name}`;
+    let cachedPromise = context.fullMetaCache.get(cacheKey);
+    if (cachedPromise == null) {
+        cachedPromise = fetchFullMetadataCached(context.fetchOpts, name, {
+            registry,
+            authHeaderValue: context.getAuthHeaderValueByURI(registry),
+            cacheDir: context.cacheDir,
+        }).then((meta) => meta.time);
+        context.fullMetaCache.set(cacheKey, cachedPromise);
+    }
+    return cachedPromise;
+}
+function pickRegistryForVersion(registries, namedRegistryPrefixes, name, tarballUrl) {
+    // If the lockfile records where the tarball lives, prefer that — scope
+    // routing (`@scope:registry`) only covers scoped packages, but named
+    // registries (`gh:`, `jsr:` aliases, custom) ship un-scoped packages whose
+    // origin we'd otherwise miss. Match the longest prefix so that two named
+    // registries sharing a host but differing by path don't collide.
+    if (tarballUrl) {
+        const normalized = tryParseUrl(tarballUrl)?.toString();
+        if (normalized) {
+            for (const prefix of namedRegistryPrefixes) {
+                if (normalized.startsWith(prefix))
+                    return prefix;
+            }
+        }
+    }
+    return pickRegistryForPackage(registries, name);
+}
+function tryParseUrl(url) {
+    try {
+        return new URL(url);
+    }
+    catch {
+        return null;
+    }
+}
+function uncheckable(policy, why) {
+    return `could not be checked against ${policy} (${why})`;
+}
+function createExcludePolicy(patterns, key) {
+    // Mirror the wrapping done by the full-resolution path
+    // (installing/deps-resolver/src/resolveDependencyTree.ts) so the error
+    // code is identical regardless of which path surfaced the invalid pattern.
+    try {
+        return createPackageVersionPolicy(patterns);
+    }
+    catch (err) {
+        if (!err || typeof err !== 'object' || !('message' in err))
+            throw err;
+        throw new PnpmError(`INVALID_${key.replace(/([A-Z])/g, '_$1').toUpperCase()}`, `Invalid value in ${key}: ${err.message}`);
+    }
+}
+function isExcluded(policy, name, version) {
+    if (!policy)
+        return false;
+    const result = policy(name);
+    if (result === true)
+        return true;
+    if (Array.isArray(result) && result.includes(version))
+        return true;
+    return false;
+}
+function isNpmRegistryResolution(resolution) {
+    if (resolution == null || typeof resolution !== 'object')
+        return false;
+    // Only plain tarball resolutions (npm registry / named registries) have no
+    // `type` field. Git / directory / binary / custom resolutions all carry one.
+    if ('type' in resolution && resolution.type != null)
+        return false;
+    // Git-hosted tarballs (codeload/gitlab/bitbucket) are special-cased in
+    // the resolver and aren't subject to release-age policy.
+    if ('gitHosted' in resolution && resolution.gitHosted)
+        return false;
+    return 'tarball' in resolution || 'integrity' in resolution;
+}
+//# sourceMappingURL=createNpmResolutionVerifier.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