🧊 npcooldown

Protect yourself from npm supply chain attacks in one command. Sets up minimumReleaseAge cooldowns across npm, pnpm, Yarn Berry, and Bun globally — so freshly-published malware never makes it into your node_modules.

npx npcooldown

The Problem

2025-2026 has been a brutal year for the JavaScript supply chain:

• Shai-Hulud worm (Sept 2025) — self-propagating npm malware that stole credentials from hundreds of packages
• chalk / debug compromise (Sept 2025) — billions of weekly downloads affected for hours
• Nx s1ngularity attack (Aug 2025) — malicious post-install scripts harvesting tokens
• axios RAT (Mar 2026) — poisoned versions live for 4 hours, phoning home within 2 seconds of npm install

The pattern is always the same: attacker compromises a maintainer token, publishes a malicious version, gets removed within hours — but anyone running npm install in that window is owned.

The fix is a "cooldown" — refuse to install package versions younger than N days. Most malicious releases are detected and yanked within 24-72 hours, so a 7-day cooldown blocks essentially every fast-burn supply chain attack.

The problem is that every package manager calls this setting something different and stores it in a different file with different units. npcooldown configures all of them at once.

How It Works

npcooldown is a transparent config writer. It walks you through one short prompt, then writes the appropriate cooldown setting to each package manager's global config file:

It only writes config for managers you actually have installed, backs up existing files with a timestamp, and merges with whatever settings you already have.

Security & Privacy

• ✅ Open source — full code transparency
• ✅ No network calls — everything is local file writes
• ✅ No data collection — your config never leaves your machine
• ✅ Timestamped backups — every file is backed up before modification
• ✅ Restrictive permissions — backups are written 0600
• ✅ Merges, never replaces — your existing config keys are preserved

Requirements

• Node.js 18+
• At least one of: npm 11.10+, pnpm 10.16+, Yarn Berry 4.10+, Bun 1.3+

(Older versions are skipped with a warning — the minimumReleaseAge settings only exist in these versions.)

Quick Start

npx npcooldown

The interactive CLI walks you through:

• Cooldown duration — 1 day, 3 days, 7 days (recommended, CISA), or custom
• Exclude patterns — packages/scopes that bypass the cooldown (e.g. @yourorg/* for internal packages you publish and install immediately)
• Strict mode — fail install if no version satisfies the age constraint (default: on)
• Block exotic subdeps — pnpm-only; prevents transitive deps from pulling from git/tarball URLs (default: on)

Then it shows you a preview of what will change in each file, asks for confirmation, and writes.

When you've run it before, existing values are read back from disk and presented as defaults — so re-running to tweak one setting doesn't make you re-type everything.

Non-interactive mode (share with your team)

After a successful run, npcooldown prints a single copy-pasteable command that reproduces your exact config:

npx npcooldown --days 7 --exclude '@epilot/*' --exclude '@yourorg/*' --yes

Paste it into your team's onboarding docs or package.json setup script. Run with --help to see all flags:

npx npcooldown --help

Recommended Cooldown Duration

The CLI defaults to 7 days — strongest protection, marginal friction. Override at any time by running npcooldown again.

Excluding Internal Packages

If you publish and immediately install your own organization's packages (e.g. CI/CD pipelines for @yourorg/*), the cooldown will block them. Add them to the exclude list:

Exclude patterns: @yourorg/*, @yourorg-internal/*

Patterns support glob-style wildcards. Pnpm and Yarn handle them natively; Bun and npm support exact package names.

What If I Need a Hotfix?

If a critical security update lands and you need it before the cooldown clears, you have three options:

1. Add the package to your exclude list — npcooldown re-run, add the name, done
2. Temporarily lower the cooldown — run npcooldown again with a shorter duration
3. Override on the command line (manager-specific) — e.g. pnpm's --minimum-release-age=0 flag for a one-off install

The default settings prioritize safety over speed, on the theory that you'd rather wait a week for chalk@5.4.1 than ship a credential-stealing worm.

Notes

• Config backups are saved as ~/.npmrc.backup.TIMESTAMP, ~/.yarnrc.yml.backup.TIMESTAMP, etc. — last 5 are kept per file.
• Running npcooldown again is idempotent — it overwrites the cooldown keys but preserves everything else.
• For project-level overrides (e.g. a single repo needs different settings), edit that repo's pnpm-workspace.yaml, .npmrc, .yarnrc.yml, or bunfig.toml directly — npcooldown only writes global config.

Related Reading

• pnpm: Mitigating supply chain attacks
• Socket: npm Introduces minimumReleaseAge
• CISA Alert on axios npm compromise
• Dani Akash: Minimum Release Age is an Underrated Supply Chain Defense

License

MIT — This tool is not affiliated with npm, Inc., pnpm, Yarn, or Oven (Bun).