feat: add minimum package age policy to prevent supply chain attacks

[PR3C14D0]

Summary

This PR implements a minimum package age policy feature for npm, similar to pnpm's minimumReleaseAge (pnpm/pnpm#9921). This security feature helps protect against supply chain attacks where malicious package versions are published and then quickly removed from the registry.

Motivation

Recent supply chain attacks have shown that malicious actors often publish compromised versions of popular packages and remove them within hours after causing damage. By enforcing a minimum age requirement, users can avoid installing versions that haven't been publicly available long enough to be vetted by the community.

Changes

New Configuration Options

• minimum-release-age (Number, default: 0)

  • Specifies the minimum age in minutes that a package version must have before it can be installed
  • When set to 0, the policy is disabled (default behavior)

• minimum-release-age-exclude (Array, default: [])

  • List of package names that should bypass the minimum age policy
  • Useful for trusted packages where immediate updates are needed

Implementation Details

1. Configuration - Added definitions for both new options in the config definitions module
2. Dependency Resolution - Modified the manifest fetching logic in Arborist to:
   • Fetch full packument to access version timestamps
   • Calculate cutoff time based on configured age
   • Add recent versions to pacote's avoid option
   • Gracefully handle errors (skips policy if packument fetch fails)
3. Documentation - Added comprehensive documentation with usage examples
4. Tests - Added 4 test cases with 9 assertions covering all scenarios

Usage Examples

Via .npmrc:

minimum-release-age=1440  # 24 hours
minimum-release-age-exclude[]=@myorg/trusted-package

Via CLI:

npm install --minimum-release-age=10
npm install some-package --minimum-release-age=60 --minimum-release-age-exclude=critical-package

Via environment variable:

npm_config_minimum_release_age=10 npm install

Testing

All tests pass:

✓ 4 test suites (9 assertions)
✓ Linting passes

Test coverage includes:

✅ Basic policy enforcement (avoids recent versions)
✅ Exclusion list functionality
✅ Disabled policy (minimum-release-age=0)
✅ Error handling (packument fetch failures)

Breaking changes

None. This is a purely additive feature with default behavior unchanged (policy disabled by default).

Related issues

Inspired by pnpm/pnpm#9921

[wraithgar]

This is already being explored in an existing PR #8802

[loudar]

This is already being explored in an existing PR #8802

The other PR doesn't seem to have an option to exclude specific packages from the rule though?

[passee]

@wraithgar there is no exclude option available in the pr you mentioned

[PR3C14D0]

This is already being explored in an existing PR #8802

The PR #8802 it does not have an exclude package option. Mine is a minimal implementation that can be extended during the time and improve it and maybe an implementation at package.json.

I would consider accepting this pull request and not closing it immediately as you did, and extending the implementation. It's one of the most requested security policies in recent times.

[fabianmartinezcaro]

thi shit is more robust than #8802, fr fr. @PR3C14D0 congrats bro

[fabianmartinezcaro]

Speechless, bro is cooking

[mikkelee]

I vote for all pull requests that implement a quarantine period and allow specifying packages that can skip quarantine. I have no opinion on the naming of the configuration keys because I will not be looking at them more than once a month at most. To be clear, and in case of ties with other pull requests: consider this a vote for the concept in general and all of them together.

[PR3C14D0]

I vote for all pull requests that implement a quarantine period and allow specifying packages that can skip quarantine. I have no opinion on the naming of the configuration keys because I will not be looking at them more than once a month at most. To be clear, and in case of ties with other pull requests: consider this a vote for the concept in general and all of them together.

Anyways, this is not a competition hmmm ☹️