When an attacker takes over a maintainer’s account and publishes a poisoned version of a popular package, the poisoned version usually lives for hours, not weeks. Somebody notices, the registry pulls it, and a clean version follows. The projects that get hurt are the ones that happened to install during those hours. A release-age gate closes off those hours: the package manager refuses to pick any version younger than a set number of days, so a release has to survive public scrutiny for a while before it can reach your machine.

By the end of this article you will have a repository on your Mac with a Node project and a Python project in which neither npm nor uv will resolve a package version published in the last 3 days, and in which Dependabot waits the same 3 days before proposing an update. You will watch both tools hold a real, current release back, and refuse it outright when you ask for it by number. You will let one urgent fix per package manager through on purpose, the way you would for a vetted security patch, without lowering the gate for everything else. And you will finish with a report that prints the age of every package your lockfiles pin, plus tests that fail if anyone removes the settings.

The settings are a few lines each. The part worth learning is where they act and where they do not: both tools apply the gate when they resolve dependencies (choose a version for each one and write it to the lockfile), and neither applies it when they replay a lockfile that already exists. That difference decides how you take an emergency patch and how you get rid of the exception afterwards.

Versions used throughout: npm 11.20.0 (Node 26.13.0) and uv 0.13.6 on macOS 27.2.1, Apple M5 Max, run on 2026-11-19 (US Eastern) / 2026-11-20 UTC. Package versions and ages in the output depend on the day you run the commands, so yours will differ; the shape of the output will not.

What you end up with

  • web/.npmrc with min-release-age=3, so npm resolves only versions at least 3 days old.
  • [tool.uv] exclude-newer = "3 days" in pyproject.toml, the same rule for uv.
  • .github/dependabot.yml with a 3-day cooldown for both package managers.
  • scripts/release_ages.py, which prints how old every locked package is.
  • tests/test_release_age.py, which fails if a setting is removed or changed.
  • A Makefile whose default target prints help.

Prerequisites

  • macOS with a terminal. Nothing here is Mac-specific beyond the install commands; the settings behave the same on Linux.
  • Node.js with npm 11.17.0 or newer. min-release-age arrived in npm 11.10.0 and the per-package exemption min-release-age-exclude in npm 11.17.0. An older npm ignores both settings with a warning, which is worse than an error because the gate looks configured and is not. Check with npm --version; upgrade with npm install -g npm@latest.
  • uv 0.9.25 or newer (install). Durations such as "3 days" in exclude-newer arrived in uv 0.9.17, and turning the gate off for a single package in 0.9.25. Check with uv --version.
  • curl, which ships with macOS, for one lookup in Step 9.
  • Assumed knowledge: what a lockfile is (package-lock.json, uv.lock: the file that records the exact version of every dependency so every install gets the same ones; a locked package is any package with an entry in one) and, for Step 6 only, what Dependabot is. A GitHub repository is needed only to see Dependabot act; everything else runs locally.

Step 1: Create the project and its .gitignore

The project is one directory with a Python project at its root and a Node project in web/, the shape of a typical repository with a backend and a frontend. The .gitignore comes first so that nothing the tools download in later steps (node_modules/, .venv/) can be committed by accident.

Create the file

mkdir -p release-age-demo/web release-age-demo/scripts release-age-demo/tests release-age-demo/.github
cd release-age-demo
touch .gitignore

Add the code: .gitignore

# Python
.venv/
__pycache__/
.pytest_cache/

# Node
node_modules/

# macOS and logs
.DS_Store
*.log

Detailed breakdown

  • .venv/ is where uv installs the Python dependencies; node_modules/ is npm’s equivalent. Both are rebuilt from the lockfiles, so neither belongs in git.
  • The lockfiles are not ignored. uv.lock and web/package-lock.json must be committed: they are half of the protection this article builds, as Step 5 shows.
  • web/.npmrc is not ignored either. Many projects ignore .npmrc because it can hold registry tokens. This one holds only settings, and a setting that lives only on one developer’s machine protects nobody else. Keep tokens in ~/.npmrc or the NODE_AUTH_TOKEN environment variable instead.

All remaining commands run from release-age-demo/ unless a step says otherwise.

Step 2: Gate npm at 3 days

npm reads project settings from a .npmrc file next to package.json. The setting that matters is min-release-age, a number of days: when npm resolves a dependency, it ignores every version published more recently than that. Start with a minimal package.json so web/ is a project npm recognizes, then add the setting.

Create the file

touch web/package.json web/.npmrc

Add the code: web/package.json

{
  "name": "web",
  "version": "1.0.0",
  "private": true
}

Add the code: web/.npmrc

# Release-age gate: never resolve a package version younger than 3 days.
# Installs from package-lock.json (npm ci) are not affected.
# No auth tokens in this file: they belong in ~/.npmrc or NODE_AUTH_TOKEN.
min-release-age=3

Detailed breakdown

  • "private": true stops npm publish from ever uploading this demo.
  • min-release-age=3 is measured in days. pnpm has a similar setting measured in minutes, so copy values between tools with care.
  • npm reads this file only when it runs inside web/. A .npmrc applies to the project whose package.json sits beside it, which is why every npm command in this article starts with cd web.

Why 3 days

The gate’s length, its window (the last N days it refuses), is a trade: every day of it is a day an attacker’s release cannot reach you, and also a day a legitimate fix cannot. Three days is this article’s default for four reasons, each of which you can check yourself.

First, npm’s own rules. An author can unpublish a version within 72 hours of publishing it, as long as no other package depends on it; after that the rules are much stricter. A 3-day gate means you only resolve versions that are past the 72 hours in which their author can unpublish them freely.

Second, the attacks this defends against are usually short-lived. The registry keeps publish times, so you can read two well-known cases straight from it:

npm view ua-parser-js time --json | grep -E '"(0\.7\.29|0\.7\.30)"'
npm view chalk time --json | grep -E '"5\.6\.[12]"'
  "0.7.29": "2021-10-22T12:15:21.378Z",
  "0.7.30": "2021-10-22T16:16:08.807Z",
  "5.6.1": "2025-09-08T13:13:05.239Z",
  "5.6.2": "2025-09-08T14:47:54.486Z",

ua-parser-js 0.7.29 was one of three hijacked versions published in October 2021, and the clean 0.7.30 followed four hours later. chalk 5.6.1 was part of the September 2025 takeover of a prolific maintainer’s account, which also hit debug 4.4.2; the clean 5.6.2 followed about 95 minutes later. A 1-day gate would have blocked both, and a 3-day gate leaves room for an attack found on a Friday evening and cleaned up on Monday.

Third, a longer window buys less than it seems. The attacks that outlast a few days are slow ones that no window catches: event-stream 3.3.6 added a dependency, flatmap-stream, on September 9, 2018; a later release of that dependency carried the malware, which was reported to npm on November 26, and the backdoored xz releases 5.6.0 and 5.6.1 shipped in February and March 2024 and were disclosed on March 29.

Fourth, the cost side: every legitimate fix waits as long as an attacker’s release does, and a long window sends you down the exemption path of Step 9 more often. Each exemption is a manual step, and manual steps invite mistakes.

Three days is this article’s default, not a rule. The right window depends on how much risk you accept and how quickly you need fixes, and some teams pick 1 day and some pick 7. The rest of the article works the same with any number; choose yours.

Confirm npm sees the setting:

cd web && npm config get min-release-age && cd ..
3

Step 3: Watch npm hold a release back

A gate that has never refused anything is untested. electron-to-chromium, a small data package with no dependencies, publishes a new version most days, which makes it a reliable thing to point the gate at. First look at its most recent releases; the registry lookup is not gated, so it shows everything:

cd web
npm view electron-to-chromium time --json | grep -vE 'created|modified' | tail -7
  "1.5.487": "2026-11-17T03:04:55.274Z",
  "1.5.488": "2026-11-17T19:04:55.642Z",
  "1.5.489": "2026-11-18T03:04:08.014Z",
  "1.5.490": "2026-11-18T11:04:09.447Z",
  "1.5.491": "2026-11-19T03:04:34.547Z",
  "1.5.492": "2026-11-19T23:04:58.074Z"
}

Now install it without naming a version, which asks npm to resolve the newest version the gate allows:

npm install electron-to-chromium
npm ls electron-to-chromium
added 1 package, and audited 2 packages in 770ms

found 0 vulnerabilities
[email protected] /Users/you/release-age-demo/web
└── [email protected]

In this run npm installed 1.5.487, not 1.5.492: the five newer versions were all published inside the last 3 days, so npm skipped them without saying so. Ask for the newest version by number and the gate refuses. This error is the point of the step:

npm install "electron-to-chromium@$(npm view electron-to-chromium version)"
cd ..
npm error code ETARGET
npm error notarget No matching version found for [email protected] with a date before 11/16/2026, 10:27:08 PM.
npm error notarget In most cases you or one of your dependencies are requesting a package version that doesn't exist.

The date in the message is the cutoff, now minus 3 days, shown in your local time zone. npm view ... version reports the newest version on the registry regardless of the gate, which is what makes the refusal visible; an install of electron-to-chromium@latest would install 1.5.487 again.

Step 4: Gate uv at 3 days

uv’s equivalent is exclude-newer in the [tool.uv] table of pyproject.toml. It takes a date or a duration, and with a duration it moves with the clock: "3 days" always means 3 days before now. Create the project with uv init --bare, which writes only a pyproject.toml and leaves out the sample code and author details a plain uv init adds.

Create the file

uv init --bare --name release-age-demo --author-from none --vcs none

Add the code: pyproject.toml

[project]
name = "release-age-demo"
version = "0.1.0"
requires-python = ">=3.14"
dependencies = []

[tool.uv]
exclude-newer = "3 days"

[tool.pytest.ini_options]
pythonpath = ["scripts"]

Detailed breakdown

  • uv init writes the [project] table; add [tool.uv] and [tool.pytest.ini_options] below it by hand. Your requires-python follows the default Python uv finds, so it may say something other than 3.14.
  • exclude-newer = "3 days" applies to every package uv resolves, including development dependencies. It also accepts an ISO 8601 duration ("P3D") or a fixed timestamp, which is useful for reproducing an old build but does not move with the clock. In pyproject.toml a fixed value must be a full timestamp such as "2026-11-01T00:00:00Z".
  • pythonpath = ["scripts"] lets the tests in Step 8 import the report script from Step 7.

Add a dependency with the same daily-release habit as electron-to-chromium. AWS publishes boto3 and its companion botocore most weekdays:

uv add boto3
Using CPython 3.14.9 interpreter at: /opt/homebrew/Caskroom/miniconda/base/bin/python
Creating virtual environment at: .venv
Resolved 8 packages in 137ms
Installed 7 packages in 21ms
 + boto3==1.44.4
 + botocore==1.44.4
 + jmespath==1.1.0
 + python-dateutil==2.9.0.post0
 + s3transfer==0.19.3
 + six==1.17.0
 + urllib3==2.8.0

The first line names whichever Python uv found, and a first download adds Downloading and Prepared lines. In this run the newest boto3 was 1.44.7, published hours earlier; 1.44.5 and 1.44.6 were also inside the window, so uv chose 1.44.4. uv downloads from PyPI, the Python package registry, and its “Resolved 8 packages” counts the project itself alongside the 7 it installed. uv records the gate in the lockfile, which matters in Step 5:

grep -A2 '^\[options\]' uv.lock
[options]
exclude-newer = "0001-01-01T00:00:00Z" # This has no effect and is included for backwards compatibility when using relative exclude-newer values.
exclude-newer-span = "P3D"

exclude-newer-span = "P3D" is the 3-day setting in ISO 8601 form. The 0001-01-01 line is a placeholder uv writes for older uv versions that expect a date there, as its comment says.

Step 5: Know what the gate does not cover

This step changes no files. It shows the limit of what you configured in Steps 2 and 4, because later steps depend on it. Both gates act when a tool resolves versions: npm install, npm update, uv add, uv lock. When a tool installs from a lockfile that already exists, it installs exactly what the lockfile says, however young that is:

(cd web && rm -rf node_modules && npm ci)
uv sync --locked
added 1 package, and audited 2 packages in 743ms

found 0 vulnerabilities
Resolved 8 packages in 3ms
Checked 7 packages in 1ms

Neither command applied the gate to the versions it installed, and that is the right behavior: a lockfile is a decision that has already been made, and npm ci and uv sync --locked exist to repeat it exactly. It means the gate protects the moment you add or update a dependency, and the committed lockfile protects every install after that. Two consequences follow:

  • Commit the lockfiles and install from them in CI with npm ci and uv sync --locked. A build that skips the lockfile resolves again on every run, so it gets whatever has just cleared the window, not the versions you tested.
  • A young version can reach the lockfile another way: a lockfile written before the gate existed, or an exemption like the one in Step 9. The report in Step 7 exists to make those visible.

Step 6: Make Dependabot wait the same 3 days

Dependabot opens pull requests that bump your dependencies, and it resolves versions on GitHub’s servers, so neither .npmrc nor pyproject.toml governs what it proposes. Its own setting is cooldown: a new version is not proposed until it is that many days old. Without it, a gated project can still receive a pull request for a version published an hour ago, and merging that pull request writes the young version straight into the lockfile.

Create the file

touch .github/dependabot.yml

Add the code: .github/dependabot.yml

version: 2
updates:
  - package-ecosystem: npm
    directory: /web
    schedule:
      interval: weekly
    cooldown:
      default-days: 3

  - package-ecosystem: uv
    directory: /
    schedule:
      interval: weekly
    cooldown:
      default-days: 3

Detailed breakdown

  • One entry per package manager and directory. directory is where the manifest lives: /web for package.json, / for pyproject.toml.
  • cooldown.default-days: 3 matches the local gate. The Dependabot options reference lists both npm and uv as supporting it, and also offers separate windows for major, minor and patch bumps (semver-major-days and so on) if you want majors to wait longer.
  • Security updates are exempt. The same reference states that cooldown applies to version updates only: when GitHub knows of a vulnerability with a fix, Dependabot opens that pull request at once, provided Dependabot security updates are turned on in the repository’s settings (this file configures version updates only). This is the fast path for urgent fixes, and it is why Step 9 is needed less often than you might fear.
  • Set it even if GitHub has a default. The reference describes a 3-day default cooldown for version updates, but that text is not shown for every GitHub plan or version. Writing the value down makes the window visible and keeps it the same wherever the repository is hosted.
  • This step cannot be run locally. Dependabot acts once the file is on the default branch of a GitHub repository; Step 8’s tests check the file’s contents in the meantime.

Step 7: Report how old every locked package is

Step 5 showed that a young version can sit in a lockfile without either tool complaining. A short script that asks each registry when every locked version was published turns that into something you can see. It uses only the Python standard library, so it adds no dependencies of its own. A locked package here means any package with an entry in a lockfile, whether you depend on it directly or not.

Create the file

touch scripts/release_ages.py

Add the code: scripts/release_ages.py

"""Report how old every locked package is, for npm and uv, against a window.

Reads web/package-lock.json and uv.lock, asks each registry when the locked
version and the newest version were published, and prints one row per locked
version. A locked version younger than the window is marked, because it can only
be there through an exemption or a lockfile written before the gate existed.
Entries that did not come from a registry (local links, git or path sources)
are skipped, since no registry knows when they were published.
"""

import gzip
import json
import sys
import time
import tomllib
import urllib.error
import urllib.request
from datetime import datetime, timezone
from pathlib import Path

WINDOW_DAYS = 3
ROOT = Path(__file__).resolve().parent.parent


def age_days(published: datetime, now: datetime) -> float:
    """Days between a publish time and now."""
    return (now - published).total_seconds() / 86400


def parse_time(value: str) -> datetime:
    """Parse the ISO 8601 timestamps both registries return."""
    return datetime.fromisoformat(value.replace("Z", "+00:00"))


def locked_npm(lock_text: str) -> set[tuple[str, str]]:
    """(name, version) of every registry package in a package-lock.json (v3)."""
    packages = json.loads(lock_text)["packages"]
    prefix = "node_modules/"
    return {
        # An aliased install records the real package name in "name".
        (entry.get("name", key.rsplit(prefix, 1)[1]), entry["version"])
        for key, entry in packages.items()
        if key.startswith(prefix) and "version" in entry and not entry.get("link")
    }


def locked_pypi(lock_text: str) -> set[tuple[str, str]]:
    """(name, version) of every registry package in a uv.lock."""
    lock = tomllib.loads(lock_text)
    return {
        (pkg["name"], pkg["version"])
        for pkg in lock.get("package", [])
        # The project itself and git or path sources have no "registry" key.
        if "registry" in pkg.get("source", {})
    }


def fetch_json(url: str, attempts: int = 3) -> dict:
    """GET a registry document, gzip-compressed: npm's can be several MB raw."""
    request = urllib.request.Request(url, headers={"Accept-Encoding": "gzip"})
    for attempt in range(1, attempts + 1):
        try:
            with urllib.request.urlopen(request, timeout=60) as response:
                body = response.read()
                if response.headers.get("Content-Encoding") == "gzip":
                    body = gzip.decompress(body)
            return json.loads(body)
        except urllib.error.HTTPError:
            raise  # the registry answered (404, 403...): retrying will not help
        except (TimeoutError, ConnectionError, urllib.error.URLError):
            if attempt == attempts:
                raise
            time.sleep(2 * attempt)
    raise AssertionError("unreachable")


def npm_times(name: str) -> tuple[dict[str, datetime], str]:
    """Publish time of every version, and the newest version, from npm."""
    doc = fetch_json(f"https://registry.npmjs.org/{name}")
    times = {
        version: parse_time(stamp)
        for version, stamp in doc["time"].items()
        if version not in ("created", "modified")
    }
    return times, doc["dist-tags"]["latest"]


def pypi_times(name: str) -> tuple[dict[str, datetime], str]:
    """Earliest upload time of every version, and the newest version, from PyPI."""
    doc = fetch_json(f"https://pypi.org/pypi/{name}/json")
    times = {
        version: min(parse_time(f["upload_time_iso_8601"]) for f in files)
        for version, files in doc["releases"].items()
        if files
    }
    return times, doc["info"]["version"]


def show_age(when: datetime | None, now: datetime) -> str:
    """An age column: days to one decimal, or "?" if the registry has no time."""
    return "?" if when is None else f"{age_days(when, now):.1f}d"


def main() -> int:
    now = datetime.now(timezone.utc)
    rows = []
    for name, version in sorted(locked_npm((ROOT / "web/package-lock.json").read_text())):
        times, latest = npm_times(name)
        rows.append(("npm", name, version, times.get(version), latest, times.get(latest)))
    for name, version in sorted(locked_pypi((ROOT / "uv.lock").read_text())):
        times, latest = pypi_times(name)
        rows.append(("pypi", name, version, times.get(version), latest, times.get(latest)))

    print(f"{'registry':<9}{'package':<22}{'locked':<14}{'age':>7}  {'newest':<14}{'age':>7}")
    young = 0
    for registry, name, version, when, latest, latest_when in rows:
        flag = ""
        if when is not None and age_days(when, now) < WINDOW_DAYS:
            flag = f"  <- under {WINDOW_DAYS} days"
            young += 1
        print(
            f"{registry:<9}{name:<22}{version:<14}{show_age(when, now):>7}  "
            f"{latest:<14}{show_age(latest_when, now):>7}{flag}"
        )
    print(f"{len(rows)} locked packages, {young} under {WINDOW_DAYS} days old")
    return 0


if __name__ == "__main__":
    sys.exit(main())

Detailed breakdown

  • locked_npm reads package-lock.json, whose packages keys are install paths such as node_modules/@scope/name or node_modules/a/node_modules/c. Taking the text after the last node_modules/ gives the package name for nested and scoped packages alike, and an entry’s own name field wins for an aliased install. It returns (name, version) pairs, because one lockfile can hold two versions of the same package and either could be the young one. Linked local packages are skipped.
  • locked_pypi reads every [[package]] table in uv.lock and keeps those with a registry source, which drops the project itself (a virtual source) and any git or path dependency. No registry can say when those were published.
  • npm_times and pypi_times fetch each package’s full history: npm’s time map gives one publish time per version, and PyPI gives an upload time per file, so the earliest file counts as the release time. The “newest” column is the registry’s own idea of the latest release (npm’s latest dist-tag, the label a publisher moves to each new release; PyPI’s newest release, not counting pre-releases), ignoring the gate.
  • The two age columns are the age of the version in the column to their left: first the locked version, then the newest one.
  • fetch_json asks for gzip and retries. npm’s full document for a package with thousands of versions is several megabytes uncompressed and much smaller compressed, and the script decompresses it itself because urllib does not. A read that stalls for 60 seconds or a dropped connection is tried up to three times, with a short pause between attempts. An HTTP error such as a 404 is raised at once, since asking again will not change the answer.
  • age_days returns the exact age, and show_age rounds it only for display, so a version 2.96 days old is flagged even though it prints as 3.0d. A version the registry has no time for prints ?.
  • The <- under 3 days flag marks any locked version younger than the window. After Steps 2 to 4 there should be none; Step 9 creates some on purpose.
  • It needs the network and makes one request per locked package. Expect around 15 to 30 seconds, most of it spent on electron-to-chromium’s large npm document, and longer on a slow connection.

Run it:

uv run scripts/release_ages.py
registry package               locked            age  newest            age
npm      electron-to-chromium  1.5.487          3.0d  1.5.492          0.2d
pypi     boto3                 1.44.4           3.3d  1.44.7           0.3d
pypi     botocore              1.44.4           3.3d  1.44.7           0.3d
pypi     jmespath              1.1.0          301.5d  1.1.0          301.5d
pypi     python-dateutil       2.9.0.post0    993.4d  4.0.0           18.9d
pypi     s3transfer            0.19.3          31.3d  0.19.3          31.3d
pypi     six                   1.17.0         715.4d  1.17.0         715.4d
pypi     urllib3               2.8.0           65.3d  2.8.0           65.3d
8 locked packages, 0 under 3 days old

Every locked version is at least 3 days old, and three of the four rows where locked and newest differ are the gate at work. python-dateutil differs for another reason: botocore requires a version below 3, so 4.0.0 was never a candidate. A gap on its own does not mean the gate held something back; the age column tells you which.

Step 8: Add tests and a Makefile

The settings from Steps 2, 4 and 6 are each one line, and a one-line setting is easy to delete in an unrelated cleanup without anyone noticing. Tests that read the files and fail when a setting is gone or changed make removing the gate a deliberate act that shows up in review. The tests read the Dependabot file with PyYAML, so add it and pytest as development dependencies first:

uv add --dev pytest pyyaml

Create the file

touch tests/test_release_age.py

Add the code: tests/test_release_age.py

"""Fail the build if a release-age setting is removed or weakened."""

import tomllib
from datetime import datetime, timezone
from pathlib import Path

import yaml

from release_ages import age_days, locked_npm, locked_pypi

ROOT = Path(__file__).resolve().parent.parent
WINDOW_DAYS = 3


def npmrc_settings() -> dict[str, list[str]]:
    settings: dict[str, list[str]] = {}
    for line in (ROOT / "web/.npmrc").read_text().splitlines():
        line = line.strip()
        if line and not line.startswith(("#", ";")):
            key, _, value = line.partition("=")
            settings.setdefault(key.strip(), []).append(value.strip())
    return settings


def test_npm_gate_is_three_days():
    assert npmrc_settings().get("min-release-age") == [str(WINDOW_DAYS)]


def test_uv_gate_is_three_days():
    pyproject = tomllib.loads((ROOT / "pyproject.toml").read_text())
    assert pyproject["tool"]["uv"]["exclude-newer"] == f"{WINDOW_DAYS} days"


def test_uv_lock_was_resolved_under_the_gate():
    lock = tomllib.loads((ROOT / "uv.lock").read_text())
    assert lock["options"]["exclude-newer-span"] == f"P{WINDOW_DAYS}D"


def test_every_dependabot_entry_has_the_cooldown():
    config = yaml.safe_load((ROOT / ".github/dependabot.yml").read_text())
    for entry in config["updates"]:
        assert entry["cooldown"]["default-days"] == WINDOW_DAYS, entry["package-ecosystem"]


def test_age_days():
    published = datetime(2026, 11, 17, 3, 0, tzinfo=timezone.utc)
    now = datetime(2026, 11, 20, 15, 0, tzinfo=timezone.utc)
    assert age_days(published, now) == 3.5


def test_locked_npm_reads_nested_scoped_and_duplicate_packages():
    lock = """{"packages": {
        "": {"name": "web"},
        "node_modules/a": {"version": "1.0.0"},
        "node_modules/@scope/b": {"version": "2.0.0"},
        "node_modules/c": {"version": "3.0.0"},
        "node_modules/a/node_modules/c": {"version": "2.9.0"},
        "node_modules/local": {"resolved": "../local", "link": true}}}"""
    assert locked_npm(lock) == {
        ("a", "1.0.0"), ("@scope/b", "2.0.0"), ("c", "3.0.0"), ("c", "2.9.0"),
    }


def test_locked_pypi_keeps_only_registry_packages():
    lock = """
[[package]]
name = "demo"
version = "0.1.0"
source = { virtual = "." }

[[package]]
name = "boto3"
version = "1.44.4"
source = { registry = "https://pypi.org/simple" }
"""
    assert locked_pypi(lock) == {("boto3", "1.44.4")}

Detailed breakdown

  • The first four tests guard the settings. npmrc_settings skips comment lines, so a commented-out # min-release-age=3 counts as removed, and the test fails with an assertion showing None instead of ['3']. It collects every value of a key because npm keeps only the last of two plain lines with the same key, so a second min-release-age line would silently override the first; the test fails on it instead.
  • test_uv_lock_was_resolved_under_the_gate checks the lockfile, not just pyproject.toml. A lockfile written before the gate existed has no exclude-newer-span, and uv sync --locked would replay it as it is.
  • The last three tests cover the report’s parsing with fixed inputs, so they run offline and give the same result on any day. test_age_days checks the arithmetic (3 days and 12 hours is 3.5 days); the parsing tests include a package locked at two versions, a linked local package and a project entry.
  • No test forbids exemptions. An exemption is a legitimate, temporary decision (Step 9); the report keeps it visible.

The Makefile collects the commands. Run with no arguments, it prints its own targets, so make alone is a safe way to find out what the project can do.

Create the file

touch Makefile

Add the code: Makefile

.DEFAULT_GOAL := help
.PHONY: help install ages test check

help: ## Show this help screen
	@grep -E '^[a-z]+:.*## ' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*## "}; {printf "  %-9s %s\n", $$1, $$2}'

install: ## Install exactly what the lockfiles pin (uv and npm)
	uv sync --locked
	cd web && npm ci

ages: ## Show how old every locked package is
	uv run scripts/release_ages.py

test: ## Run the tests that guard the release-age settings
	uv run pytest -v

check: test ages ## Run the tests, then the age report

Detailed breakdown

  • .DEFAULT_GOAL := help makes plain make run help, which lists every target that has a ## description on its line.
  • install uses the lockfile commands from Step 5, so a fresh clone gets exactly the versions the lockfiles pin and the gate is never involved.
  • check runs the offline tests first, then the network-dependent report.
  • Recipe lines start with a tab, not spaces; make rejects spaces with missing separator.
make
make test
  help      Show this help screen
  install   Install exactly what the lockfiles pin (uv and npm)
  ages      Show how old every locked package is
  test      Run the tests that guard the release-age settings
  check     Run the tests, then the age report
uv run pytest -v
============================= test session starts ==============================
platform darwin -- Python 3.14.9, pytest-9.2.0, pluggy-1.7.0 -- /Users/you/release-age-demo/.venv/bin/python
cachedir: .pytest_cache
rootdir: /Users/you/release-age-demo
configfile: pyproject.toml
collecting ... collected 7 items

tests/test_release_age.py::test_npm_gate_is_three_days PASSED            [ 14%]
tests/test_release_age.py::test_uv_gate_is_three_days PASSED             [ 28%]
tests/test_release_age.py::test_uv_lock_was_resolved_under_the_gate PASSED [ 42%]
tests/test_release_age.py::test_every_dependabot_entry_has_the_cooldown PASSED [ 57%]
tests/test_release_age.py::test_age_days PASSED                          [ 71%]
tests/test_release_age.py::test_locked_npm_reads_nested_scoped_and_duplicate_packages PASSED [ 85%]
tests/test_release_age.py::test_locked_pypi_keeps_only_registry_packages PASSED [100%]

============================== 7 passed in 0.02s ===============================

Step 9: Let one vetted fix through in each tool

When a critical vulnerability lands in a package you depend on, the fixed version may be younger than your window. The answer is to exempt that package, and only that package, for as long as the fix takes to age past the window. It is never to lower or disable the gate for everything.

Check two things first, because an exemption switches off the protection for exactly the release an attacker would most like you to rush:

  • The advisory is real. Find it in the GitHub Advisory Database, the package’s own security page, or the output of npm audit or pip-audit, not only in a message urging you to upgrade.
  • The fixed version comes from the real maintainers. It should match the advisory’s “patched versions” and the project’s release notes or git tag.

Before exempting anything, check whether you need to: Dependabot’s security updates skip the cooldown (Step 6), so on GitHub the fix may already be waiting as a pull request. The rest of this step is the manual path, for when it is not. The demo treats the newest boto3 and electron-to-chromium as the patched versions; in real use, take the version from the advisory.

Exempt the package in uv

Read the fixed version into a shell variable, then require it. Requiring it with uv add raises the minimum in pyproject.toml, which matters at the end of this step:

FIXED=$(curl -s https://pypi.org/pypi/boto3/json | uv run python -c 'import json, sys; print(json.load(sys.stdin)["info"]["version"])')
echo "$FIXED"
uv add "boto3>=$FIXED"
1.44.7
error: Failed to add dependencies
  cause: No solution found when resolving dependencies
  cause: Because only boto3<=1.44.4 is available and your project depends on boto3>=1.44.7, we can conclude that your project's requirements are unsatisfiable.

hint: `boto3` was filtered by `exclude-newer` to only include packages uploaded before 2026-11-17T03:27:52.649565Z. The latest version satisfying the requirement is v1.44.7, published at 2026-11-19T20:34:12.236Z. Consider using `exclude-newer-package` to override the cutoff for this package.

hint: If you want to add the package regardless of the failed resolution, provide the `--frozen` flag to skip locking and syncing

That refusal is the gate working, and the hint names the setting to use. Add an exclude-newer-package line under exclude-newer, with a comment that says why and when, so nobody forgets why the exemption exists or when to remove it.

Create the file

# pyproject.toml already exists; edit its [tool.uv] table.

Add the code: pyproject.toml (the [tool.uv] table)

[tool.uv]
exclude-newer = "3 days"
# Exempt for <advisory id>, added 2026-11-19. Remove once the fix is 3 days old.
exclude-newer-package = { boto3 = false }

Detailed breakdown

  • { boto3 = false } turns the gate off for boto3 alone. A package can also be given its own date or duration instead of false.
  • The comment records when to remove it, and the report’s flag confirms it. Neither tool removes an exemption for you.

Try again:

uv add "boto3>=$FIXED"
error: Failed to add dependencies
  cause: No solution found when resolving dependencies
  cause: Because only botocore<=1.44.4 is available and boto3>=1.44.7 depends on botocore>=1.44.7,<1.45.0, we can conclude that boto3>=1.44.7 cannot be used.
         And because your project depends on boto3>=1.44.7, we can conclude that your project's requirements are unsatisfiable.

hint: `botocore` was filtered by `exclude-newer` to only include packages uploaded before 2026-11-17T03:27:52.682614Z. The latest version satisfying the requirement is v1.44.7, published at 2026-11-19T20:34:04.837Z. Consider using `exclude-newer-package` to override the cutoff for this package.

hint: If you want to add the package regardless of the failed resolution, provide the `--frozen` flag to skip locking and syncing

This second failure is also intended, and it is a common way an emergency exemption goes wrong. boto3 1.44.7 requires botocore 1.44.7, which is just as young, and the gate still covers botocore. Real fixes often span packages released together like this, so an exemption has to cover all of them. Had you run uv lock --upgrade-package boto3 instead of uv add with a minimum, uv would have kept 1.44.4 without an error or warning, and the fix would never have landed. Extend the exemption to botocore:

Create the file

# Edit the exclude-newer-package line in pyproject.toml's [tool.uv] table.

Add the code: pyproject.toml (the [tool.uv] table)

[tool.uv]
exclude-newer = "3 days"
# Exempt for <advisory id>, added 2026-11-19. Remove once the fix is 3 days old.
exclude-newer-package = { boto3 = false, botocore = false }

Detailed breakdown

  • Exempt exactly the packages the fix needs. The resolver’s error names each one, so add them one at a time until it succeeds rather than guessing.
  • uv writes the exemption into uv.lock under [options.exclude-newer-package], so uv sync --locked in CI agrees with your machine about what is allowed.
uv add "boto3>=$FIXED"
Resolved 15 packages in 3ms
Uninstalled 2 packages in 163ms
Installed 2 packages in 13ms
 - boto3==1.44.4
 + boto3==1.44.7
 - botocore==1.44.4
 + botocore==1.44.7

Exempt the package in npm

npm’s exemption is a min-release-age-exclude line per package, again with a comment that records why and when:

Create the file

# web/.npmrc already exists; add two lines at the end.

Add the code: web/.npmrc (lines to add)

# Exempt for <advisory id>, added 2026-11-19. Remove once the fix is 3 days old.
min-release-age-exclude[]=electron-to-chromium

Detailed breakdown

  • Write the key with [], one package per line. .npmrc keeps only the last of two plain lines with the same key, so a second min-release-age-exclude= line would silently replace the first, while min-release-age-exclude[]= lines add up to a list. Each entry can also be a glob such as @your-org/*, which is how you would let your own organization’s packages update immediately.
  • npm audit fix respects the gate too. Since npm 11.18.0 it warns when min-release-age blocks a fix, which is often how you find out you need an exemption.
cd web
npm install "electron-to-chromium@$(npm view electron-to-chromium version)"
npm ls electron-to-chromium
cd ..
changed 1 package in 18s
[email protected] /Users/you/release-age-demo/web
└── [email protected]

Installing the version by number writes ^1.5.492 to package.json, the npm counterpart of the minimum you gave uv.

See the exemptions, and remove them on time

The report now shows exactly what the exemptions let in:

make ages
uv run scripts/release_ages.py
registry package               locked            age  newest            age
npm      electron-to-chromium  1.5.492          0.2d  1.5.492          0.2d  <- under 3 days
pypi     boto3                 1.44.7           0.3d  1.44.7           0.3d  <- under 3 days
pypi     botocore              1.44.7           0.3d  1.44.7           0.3d  <- under 3 days
pypi     colorama              0.4.6         1487.0d  0.4.6         1487.0d
pypi     iniconfig             2.3.1           44.2d  2.3.1           44.2d
pypi     jmespath              1.1.0          301.5d  1.1.0          301.5d
pypi     packaging             26.3           107.4d  26.3           107.4d
pypi     pluggy                1.7.0           35.7d  1.7.0           35.7d
pypi     pygments              2.21.0          94.8d  2.21.0          94.8d
pypi     pytest                9.2.0           23.2d  9.2.0           23.2d
pypi     python-dateutil       2.9.0.post0    993.4d  4.0.0           18.9d
pypi     pyyaml                6.0.3          420.2d  6.0.3          420.2d
pypi     s3transfer            0.19.3          31.3d  0.19.3          31.3d
pypi     six                   1.17.0         715.4d  1.17.0         715.4d
pypi     urllib3               2.8.0           65.3d  2.8.0           65.3d
15 locked packages, 3 under 3 days old

The three flagged rows are the exemptions, and nothing else is young. The development dependencies from Step 8 appear too, because they are in uv.lock.

Remove each exemption once its version is older than the window: the flag disappears from the report, which is the signal. Removing one early behaves differently in the two tools. In uv, delete the exclude-newer-package line and its comment, and check the lockfile:

uv lock --check
Resolving despite existing lockfile due to removal of exclude newer for package `boto3`
error: No solution found when resolving dependencies
  cause: Because boto3>1.44.4 was published after the exclude newer time and your project depends on boto3>=1.44.7, we can conclude that your project's requirements are unsatisfiable.

The “exclude newer time” in the message is uv’s name for the cutoff. uv refuses, and uv sync --locked in CI would refuse the same way, so an early removal cannot slip through. That is the boto3>=1.44.7 minimum at work. Without it, uv would have resolved again and gone back to 1.44.4, undoing the fix with no error. Put the line back until the report stops flagging boto3.

npm does not check. Delete the exemption line and its comment from web/.npmrc and reinstall from the lockfile:

cd web && rm -rf node_modules && npm ci && npm ls electron-to-chromium; cd ..
added 1 package, and audited 2 packages in 3s

found 0 vulnerabilities
[email protected] /Users/you/release-age-demo/web
└── [email protected]

npm ci installs the young version without complaint, as Step 5 said it would. The only place an early removal shows up is a resolve from scratch: with the lockfile deleted, npm install would fail with ETARGET until 1.5.492 is 3 days old, because package.json now asks for at least that version. The report tells you when the exemption has done its job, so put the line back as well and leave both exemptions in place until it does.

Step 10: Run the whole check

With the exemptions back in place, make check runs the tests and the report together, which is the state this article set out to reach: both package managers gated at 3 days, Dependabot configured to match, one vetted fix per tool let through on purpose, and every young version in the lockfiles accounted for.

make check
uv run pytest -v
============================= test session starts ==============================
platform darwin -- Python 3.14.9, pytest-9.2.0, pluggy-1.7.0 -- /Users/you/release-age-demo/.venv/bin/python
cachedir: .pytest_cache
rootdir: /Users/you/release-age-demo
configfile: pyproject.toml
collecting ... collected 7 items

tests/test_release_age.py::test_npm_gate_is_three_days PASSED            [ 14%]
tests/test_release_age.py::test_uv_gate_is_three_days PASSED             [ 28%]
tests/test_release_age.py::test_uv_lock_was_resolved_under_the_gate PASSED [ 42%]
tests/test_release_age.py::test_every_dependabot_entry_has_the_cooldown PASSED [ 57%]
tests/test_release_age.py::test_age_days PASSED                          [ 71%]
tests/test_release_age.py::test_locked_npm_reads_nested_scoped_and_duplicate_packages PASSED [ 85%]
tests/test_release_age.py::test_locked_pypi_keeps_only_registry_packages PASSED [100%]

============================== 7 passed in 0.02s ===============================
uv run scripts/release_ages.py
registry package               locked            age  newest            age
npm      electron-to-chromium  1.5.492          0.2d  1.5.492          0.2d  <- under 3 days
pypi     boto3                 1.44.7           0.3d  1.44.7           0.3d  <- under 3 days
pypi     botocore              1.44.7           0.3d  1.44.7           0.3d  <- under 3 days
pypi     colorama              0.4.6         1487.0d  0.4.6         1487.0d
pypi     iniconfig             2.3.1           44.2d  2.3.1           44.2d
pypi     jmespath              1.1.0          301.5d  1.1.0          301.5d
pypi     packaging             26.3           107.4d  26.3           107.4d
pypi     pluggy                1.7.0           35.7d  1.7.0           35.7d
pypi     pygments              2.21.0          94.8d  2.21.0          94.8d
pypi     pytest                9.2.0           23.3d  9.2.0           23.3d
pypi     python-dateutil       2.9.0.post0    993.4d  4.0.0           18.9d
pypi     pyyaml                6.0.3          420.3d  6.0.3          420.3d
pypi     s3transfer            0.19.3          31.3d  0.19.3          31.3d
pypi     six                   1.17.0         715.4d  1.17.0         715.4d
pypi     urllib3               2.8.0           65.3d  2.8.0           65.3d
15 locked packages, 3 under 3 days old

Three days later the same command reports 0 under 3 days old with the exemptions still in place; that is when you delete them, run uv lock, and commit.

Troubleshooting

  • npm warn Unknown project config "min-release-age" means your npm is older than 11.10.0 and is ignoring the gate. Upgrade npm; Node’s bundled npm can lag behind.
  • ETARGET ... with a date before ... on an install you expected to work means every version matching your range is younger than the window. Use an older range, wait, or exempt the package as in Step 9 if the reason is urgent.
  • uv add reports “No solution found” with an exclude-newer hint for the same reason. The hint names the package and its newest version.
  • uv sync --locked fails with “Resolving despite existing lockfile” after you edit [tool.uv]: the lockfile records the gate and its exemptions, so run uv lock after changing either and commit both files together.
  • The report stops with TimeoutError on a slow connection while it downloads a large registry document. Each read waits 60 seconds and is tried three times; run it again, or on a faster network.

Recap

You configured npm (min-release-age=3 in web/.npmrc) and uv (exclude-newer = "3 days" in pyproject.toml) to ignore any version published in the last 3 days, and Dependabot (cooldown.default-days: 3) to wait the same. You saw both tools hold back a current release and refuse one by number. You learned that the gate acts only when versions are resolved, so the committed lockfile plus npm ci and uv sync --locked protect every install after that. You let a vetted fix through in each tool by exempting exactly the packages it needed, set a minimum version so an early removal fails loudly, and used a report and tests to keep the whole arrangement visible.

Next improvements:

  • Run make test in CI so a pull request that removes a setting fails.
  • Apply the same settings to every repository you maintain; the .npmrc and [tool.uv] lines carry over unchanged.
  • Rust, Go, Swift and Docker have no equivalent setting built in, and need the lockfile-and-cooldown half of this approach on its own.