Skip to main content
Safe Chain requires packages to be at least a configurable number of hours old before allowing their installation. By default, this threshold is 48 hours. This provides an additional security layer during the critical window when newly published packages are most vulnerable to containing undetected malware.

​
How enforcement works

Enforcement differs by ecosystem: npm-based package managers (npm, npx, yarn, pnpm, pnpx, bun, bunx) Safe Chain uses two complementary modes:
  1. During normal package resolution, Safe Chain suppresses versions that are newer than the configured minimum age from the package metadata returned by the registry.
  2. For direct package download requests that bypass the metadata flow, Safe Chain blocks the request using a cached list of newly released packages.
Python package managers (pip, pip3, uv, poetry, pipx) Safe Chain blocks direct package download requests using a cached list of newly released packages.

​
Configuration

You can set the minimum package age through multiple sources, applied in this priority order:
1

CLI argument (highest priority)

npm install express --safe-chain-minimum-package-age-hours=48
2

Environment variable

export SAFE_CHAIN_MINIMUM_PACKAGE_AGE_HOURS=48
npm install express
3

Config file

Add minimumPackageAgeHours to ~/.safe-chain/config.json:
{
  "minimumPackageAgeHours": 48
}
Setting minimumPackageAgeHours to 0 disables the minimum package age check entirely for all packages. Use exclusions to allow specific packages instead.

​
Skipping the check entirely

To bypass the minimum package age check for a single command, use the --safe-chain-skip-minimum-package-age flag: 
npm install express --safe-chain-skip-minimum-package-age

​
Excluding specific packages

You can allow specific packages to bypass the minimum age check without disabling it globally. Exclusions from both the environment variable and the config file are merged together. 
# Exclude a single package
export SAFE_CHAIN_MINIMUM_PACKAGE_AGE_EXCLUSIONS="requests"

# Exclude multiple packages (comma-separated)
export SAFE_CHAIN_MINIMUM_PACKAGE_AGE_EXCLUSIONS="react,lodash"

# Exclude all packages under an npm scope
export SAFE_CHAIN_MINIMUM_PACKAGE_AGE_EXCLUSIONS="@aikidosec/*"
Use the @scope/* wildcard syntax to trust all packages published under a given npm organization scope.

Build docs developers (and LLMs) love

Get started for freeTalk to us