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/.npmrcwithmin-release-age=3, so npm resolves only versions at least 3 days old.[tool.uv] exclude-newer = "3 days"inpyproject.toml, the same rule for uv..github/dependabot.ymlwith a 3-daycooldownfor 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
Makefilewhose 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-agearrived in npm 11.10.0 and the per-package exemptionmin-release-age-excludein 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 withnpm --version; upgrade withnpm install -g npm@latest. - uv 0.9.25 or newer (install).
Durations such as
"3 days"inexclude-newerarrived in uv 0.9.17, and turning the gate off for a single package in 0.9.25. Check withuv --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.lockandweb/package-lock.jsonmust be committed: they are half of the protection this article builds, as Step 5 shows. web/.npmrcis not ignored either. Many projects ignore.npmrcbecause 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~/.npmrcor theNODE_AUTH_TOKENenvironment 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": truestopsnpm publishfrom ever uploading this demo.min-release-age=3is 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.npmrcapplies to the project whosepackage.jsonsits beside it, which is why every npm command in this article starts withcd 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 initwrites the[project]table; add[tool.uv]and[tool.pytest.ini_options]below it by hand. Yourrequires-pythonfollows 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. Inpyproject.tomla 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 cianduv 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.
directoryis where the manifest lives:/webforpackage.json,/forpyproject.toml. cooldown.default-days: 3matches 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-daysand 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_npmreadspackage-lock.json, whosepackageskeys are install paths such asnode_modules/@scope/nameornode_modules/a/node_modules/c. Taking the text after the lastnode_modules/gives the package name for nested and scoped packages alike, and an entry’s ownnamefield 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_pypireads every[[package]]table inuv.lockand keeps those with aregistrysource, which drops the project itself (avirtualsource) and any git or path dependency. No registry can say when those were published.npm_timesandpypi_timesfetch each package’s full history: npm’stimemap 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’slatestdist-tag, the label a publisher moves to each new release; PyPI’s newest release, not counting pre-releases), ignoring the gate.- The two
agecolumns are the age of the version in the column to their left: first the locked version, then the newest one. fetch_jsonasks 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 becauseurllibdoes 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_daysreturns the exact age, andshow_agerounds it only for display, so a version 2.96 days old is flagged even though it prints as3.0d. A version the registry has no time for prints?.- The
<- under 3 daysflag 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_settingsskips comment lines, so a commented-out# min-release-age=3counts as removed, and the test fails with an assertion showingNoneinstead 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 secondmin-release-ageline would silently override the first; the test fails on it instead. test_uv_lock_was_resolved_under_the_gatechecks the lockfile, not justpyproject.toml. A lockfile written before the gate existed has noexclude-newer-span, anduv sync --lockedwould 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_dayschecks 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 := helpmakes plainmakerunhelp, which lists every target that has a##description on its line.installuses the lockfile commands from Step 5, so a fresh clone gets exactly the versions the lockfiles pin and the gate is never involved.checkruns the offline tests first, then the network-dependent report.- Recipe lines start with a tab, not spaces;
makerejects spaces withmissing 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 auditorpip-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 forboto3alone. A package can also be given its own date or duration instead offalse.- 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.lockunder[options.exclude-newer-package], souv sync --lockedin 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..npmrckeeps only the last of two plain lines with the same key, so a secondmin-release-age-exclude=line would silently replace the first, whilemin-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 fixrespects the gate too. Since npm 11.18.0 it warns whenmin-release-ageblocks 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 addreports “No solution found” with anexclude-newerhint for the same reason. The hint names the package and its newest version.uv sync --lockedfails with “Resolving despite existing lockfile” after you edit[tool.uv]: the lockfile records the gate and its exemptions, so runuv lockafter changing either and commit both files together.- The report stops with
TimeoutErroron 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 testin CI so a pull request that removes a setting fails. - Apply the same settings to every repository you maintain; the
.npmrcand[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.