feat(resolver): add PyPI cooldown policy to reject recently-published versions

Adds --pypi-min-age (FROMAGER_PYPI_MIN_AGE) to reject package versions
published fewer than N days ago, protecting against supply-chain attacks.
Enforcement is automatic for all PyPI resolutions including custom plugins,
and fail-closed when upload_time metadata is missing.

Co-Authored-By: Claude <claude@anthropic.com>
Related: #877

Author: ryanpetrello

docs/how-tos/index.rst

@@ -48,6 +48,7 @@ Customize builds with overrides, variants, and version handling.
    pyproject-overrides
    multiple-versions
    pre-release-versions
+   pypi-cooldown
 
 Analyzing Builds
 ----------------

docs/how-tos/pypi-cooldown.rst

@@ -0,0 +1,88 @@
+Protect Against Supply-Chain Attacks with PyPI Cooldown
+========================================================
+
+Fromager's PyPI cooldown policy rejects package versions that were published
+fewer than a configured number of days ago. This protects automated builds from
+supply-chain attacks where a malicious version is published and immediately
+pulled in before it can be reviewed.
+
+How It Works
+------------
+
+When a cooldown is active, any candidate whose ``upload-time`` is more recent
+than the cutoff (current time minus the configured minimum age) is not
+considered a valid option during constraint resolution. If no versions of a
+package satisfy both the cooldown window and any other provided constraints,
+resolution fails with an informative error.
+
+The cutoff timestamp is fixed at the start of each run, so all package
+resolutions within a single bootstrap share the same boundary.
+
+Enabling the Cooldown
+---------------------
+
+Use the global ``--pypi-min-age`` flag, or set the equivalent environment
+variable ``FROMAGER_PYPI_MIN_AGE``:
+
+.. code-block:: bash
+
+   # Reject versions published in the last 7 days
+   fromager --pypi-min-age 7 bootstrap -r requirements.txt
+
+   # Same, via environment variable (useful for CI and builder integrations)
+   FROMAGER_PYPI_MIN_AGE=7 fromager bootstrap -r requirements.txt
+
+   # Disable the cooldown (default)
+   fromager --pypi-min-age 0 bootstrap -r requirements.txt
+
+The ``--pypi-min-age`` flag accepts a non-negative integer number of days.
+A value of ``0`` (the default) disables the check entirely.
+
+Scope
+-----
+
+The cooldown applies to **all resolutions** in a run, including transitive
+dependencies and packages fetched from a custom ``--sdist-server-url``. It does
+not apply to packages resolved from Git URLs, which use a separate code path.
+
+Note that when using a private package index, the cooldown depends on
+``upload-time`` being present in the index's PEP 691 JSON responses. If the
+index does not provide that metadata, candidates will be rejected under the
+fail-closed policy described below.
+
+Explicit version pins (``package==1.2.3``) are subject to the same cooldown as
+unpinned requirements. If the pinned version was published within the cooldown
+window, resolution will fail. To unblock a specific run, set ``--pypi-min-age 0``
+or use the environment variable.
+
+Fail-Closed Behavior
+--------------------
+
+If a candidate has no ``upload-time`` metadata — which can occur with older
+PyPI Simple HTML responses — it is rejected when a cooldown is active. Fromager
+uses the `PEP 691 JSON Simple API`_ when fetching package metadata, which
+reliably includes upload timestamps.
+
+.. _PEP 691 JSON Simple API: https://peps.python.org/pep-0691/
+
+Example
+-------
+
+Given a package ``example-pkg`` with three available versions:
+
+* ``2.0.0`` — published 3 days ago
+* ``1.9.0`` — published 45 days ago
+* ``1.8.0`` — published 120 days ago
+
+With a 7-day cooldown, ``2.0.0`` is blocked and ``1.9.0`` is selected:
+
+.. code-block:: bash
+
+   fromager --pypi-min-age 7 bootstrap example-pkg
+
+With a 60-day cooldown, both ``2.0.0`` and ``1.9.0`` are blocked and ``1.8.0``
+is selected:
+
+.. code-block:: bash
+
+   fromager --pypi-min-age 60 bootstrap example-pkg

src/fromager/__main__.py

@@ -1,5 +1,6 @@
 #!/usr/bin/env python3
 
+import datetime
 import logging
 import pathlib
 import sys
@@ -143,6 +144,15 @@
     help="Build sdist and when with network isolation (unshare -cn)",
     show_default=True,
 )
+@click.option(
+    "--pypi-min-age",
+    type=click.IntRange(min=0),
+    default=0,
+    help=(
+        "Reject PyPI package versions published fewer than this many days ago "
+        "(0 disables the check). Also settable via FROMAGER_PYPI_MIN_AGE."
+    ),
+)
 @click.pass_context
 def main(
     ctx: click.Context,
@@ -163,6 +173,7 @@ def main(
     variant: str,
     jobs: int | None,
     network_isolation: bool,
+    pypi_min_age: int,
 ) -> None:
     # Save the debug flag so invoke_main() can use it.
     global _DEBUG
@@ -249,6 +260,11 @@ def main(
         network_isolation=network_isolation,
         max_jobs=jobs,
         settings_dir=settings_dir,
+        pypi_cooldown=(
+            context.Cooldown(min_age=datetime.timedelta(days=pypi_min_age))
+            if pypi_min_age > 0
+            else None
+        ),
     )
     wkctx.setup()
     ctx.obj = wkctx

src/fromager/bootstrapper.py

@@ -1017,6 +1017,7 @@ def _download_wheel_from_cache(
                 sdist_server_url=self.cache_wheel_server_url,
                 include_sdists=False,
                 include_wheels=True,
+                skip_cooldowns=True,
             )
             wheelfile_name = pathlib.Path(urlparse(wheel_url).path)
             pbi = self.ctx.package_build_info(req)

src/fromager/context.py

@@ -1,6 +1,8 @@
 from __future__ import annotations
 
 import collections
+import dataclasses
+import datetime
 import logging
 import os
 import pathlib
@@ -31,6 +33,20 @@
 ROOT_BUILD_REQUIREMENT = canonicalize_name("", validate=False)
 
 
+@dataclasses.dataclass
+class Cooldown:
+    """Policy for rejecting recently-published package versions.
+
+    bootstrap_time is fixed at construction so all resolutions in a single run
+    share the same cutoff.
+    """
+
+    min_age: datetime.timedelta
+    bootstrap_time: datetime.datetime = dataclasses.field(
+        default_factory=lambda: datetime.datetime.now(datetime.UTC)
+    )
+
+
 class WorkContext:
     def __init__(
         self,
@@ -46,6 +62,7 @@ def __init__(
         max_jobs: int | None = None,
         settings_dir: pathlib.Path | None = None,
         wheel_server_url: str = "",
+        pypi_cooldown: Cooldown | None = None,
     ):
         if active_settings is None:
             active_settings = packagesettings.Settings(
@@ -95,6 +112,8 @@ def __init__(
 
         self._parallel_builds = False
 
+        self.pypi_cooldown: Cooldown | None = pypi_cooldown
+
     def enable_parallel_builds(self) -> None:
         self._parallel_builds = True
 

src/fromager/resolver.py

@@ -33,6 +33,7 @@
 from . import overrides
 from .candidate import Candidate
 from .constraints import Constraints
+from .context import Cooldown
 from .extras_provider import ExtrasProvider
 from .http_retry import RETRYABLE_EXCEPTIONS, retry_on_exception
 from .request_session import session
@@ -48,6 +49,9 @@
 PYTHON_VERSION = Version(python_version())
 DEBUG_RESOLVER = os.environ.get("DEBUG_RESOLVER", "")
 PYPI_SERVER_URL = "https://pypi.org/simple"
+
+# Sentinel meaning "inherit cooldown from ctx.pypi_cooldown".
+_UNSET: typing.Final[object] = object()
 GITHUB_URL = "https://github.com"
 
 # all supported tags
@@ -85,8 +89,12 @@ def resolve(
     include_wheels: bool = True,
     req_type: RequirementType | None = None,
     ignore_platform: bool = False,
+    skip_cooldowns: bool = False,
 ) -> tuple[str, Version]:
     # Create the (reusable) resolver.
+    extra_kwargs: dict[str, object] = {}
+    if skip_cooldowns:
+        extra_kwargs["cooldown"] = None
     provider = overrides.find_and_invoke(
         req.name,
         "get_resolver_provider",
@@ -98,6 +106,7 @@ def resolve(
         sdist_server_url=sdist_server_url,
         req_type=req_type,
         ignore_platform=ignore_platform,
+        **extra_kwargs,
     )
     return resolve_from_provider(provider, req)
 
@@ -110,6 +119,7 @@ def default_resolver_provider(
     include_wheels: bool,
     req_type: RequirementType | None = None,
     ignore_platform: bool = False,
+    cooldown: Cooldown | None | object = _UNSET,
 ) -> (
     PyPIProvider
     | GenericProvider
@@ -118,13 +128,19 @@ def default_resolver_provider(
     | VersionMapProvider
 ):
     """Lookup resolver provider to resolve package versions"""
+    effective_cooldown = (
+        ctx.pypi_cooldown
+        if cooldown is _UNSET
+        else typing.cast(Cooldown | None, cooldown)
+    )
     return PyPIProvider(
         include_sdists=include_sdists,
         include_wheels=include_wheels,
         sdist_server_url=sdist_server_url,
         constraints=ctx.constraints,
         req_type=req_type,
         ignore_platform=ignore_platform,
+        cooldown=effective_cooldown,
     )
 
 
@@ -397,11 +413,13 @@ def __init__(
         constraints: Constraints | None = None,
         req_type: RequirementType | None = None,
         use_resolver_cache: bool = True,
+        cooldown: Cooldown | None = None,
     ):
         super().__init__()
         self.constraints = constraints or Constraints()
         self.req_type = req_type
         self.use_cache_candidates = use_resolver_cache
+        self.cooldown = cooldown
 
     @property
     def cache_key(self) -> str:
@@ -470,10 +488,38 @@ def validate_candidate(
                     f"{identifier}: skipping bad version {candidate.version} from {bad_versions}"
                 )
             return False
-        for r in identifier_reqs:
-            if self.is_satisfied_by(requirement=r, candidate=candidate):
-                return True
-        return False
+
+        if not any(
+            self.is_satisfied_by(requirement=r, candidate=candidate)
+            for r in identifier_reqs
+        ):
+            return False
+
+        # Fail closed: if upload_time is missing we cannot verify the package
+        # is old enough, so we reject it rather than silently bypassing the policy.
+        if self.cooldown is not None:
+            if candidate.upload_time is None:
+                if DEBUG_RESOLVER:
+                    logger.debug(
+                        "%s: skipping %s — upload_time unknown, required for cooldown",
+                        identifier,
+                        candidate.version,
+                    )
+                return False
+            cutoff = self.cooldown.bootstrap_time - self.cooldown.min_age
+            if candidate.upload_time > cutoff:
+                if DEBUG_RESOLVER:
+                    age = self.cooldown.bootstrap_time - candidate.upload_time
+                    logger.debug(
+                        "%s: skipping %s uploaded %s ago (cooldown: %s)",
+                        identifier,
+                        candidate.version,
+                        age,
+                        self.cooldown.min_age,
+                    )
+                return False
+
+        return True
 
     def get_preference(
         self,
@@ -608,11 +654,13 @@ def __init__(
         ignore_platform: bool = False,
         *,
         use_resolver_cache: bool = True,
+        cooldown: Cooldown | None = None,
     ):
         super().__init__(
             constraints=constraints,
             req_type=req_type,
             use_resolver_cache=use_resolver_cache,
+            cooldown=cooldown,
         )
         self.include_sdists = include_sdists
         self.include_wheels = include_wheels
@@ -683,6 +731,35 @@ def _get_no_match_error_message(
         else:
             file_type_info = "wheels"
 
+        # If a cooldown is active, check whether it's responsible for the
+        # failure so we can give a more actionable error message.
+        if self.cooldown is not None:
+            cutoff = self.cooldown.bootstrap_time - self.cooldown.min_age
+            all_candidates = list(self._find_cached_candidates(identifier))
+            missing_time = [c for c in all_candidates if c.upload_time is None]
+            cooldown_blocked = [
+                c
+                for c in all_candidates
+                if c.upload_time is not None and c.upload_time > cutoff
+            ]
+            if missing_time and not cooldown_blocked:
+                return (
+                    f"found {len(missing_time)} candidate(s) for {r} but none have "
+                    f"upload timestamp metadata; cannot enforce the "
+                    f"{self.cooldown.min_age.days}-day cooldown"
+                )
+            if cooldown_blocked:
+                oldest_days = min(
+                    (self.cooldown.bootstrap_time - c.upload_time).days
+                    for c in cooldown_blocked
+                    if c.upload_time is not None
+                )
+                return (
+                    f"found {len(cooldown_blocked)} candidate(s) for {r} but all "
+                    f"are within the {self.cooldown.min_age.days}-day cooldown window "
+                    f"(oldest is {oldest_days} day(s) old)"
+                )
+
         return (
             f"found no match for {r} using {self.get_provider_description()}, "
             f"searching for {file_type_info}, {prerelease_info} pre-release versions"

src/fromager/wheels.py

@@ -476,6 +476,7 @@ def resolve_prebuilt_wheel(
                 req_type=req_type,
                 # pre-built wheels must match platform
                 ignore_platform=False,
+                skip_cooldowns=True,
             )
         except Exception as e:
             excs.append(e)