warehouse13/docs/NPM-PACKAGE-AGE-POLICY.md

NPM Package Age Policy

Requirement

All npm packages must be at least 2 weeks old before they can be used in this project. This ensures:

• Package stability
• Security vulnerability disclosure time
• Compliance with organizational security policies

How It Works

1. Package Version Pinning

The project uses exact version pinning in package.json to prevent automatic updates:

{
  "dependencies": {
    "@angular/core": "19.2.7",  // Exact version, not "^19.2.7" or "~19.2.7"
    // ...
  }
}

The frontend/.npmrc file enforces this:

save-exact=true
package-lock=true

2. Automated Age Checking

Use the provided script to verify all packages meet the 2-week requirement:

# Check if all packages are at least 2 weeks old
node scripts/check-package-age.js

This script:

• Queries npm registry for publish dates
• Calculates age of each package
• Fails if any package is newer than 14 days
• Shows detailed age information for all packages

3. Installation Process

Always use npm ci instead of npm install:

cd frontend
npm ci  # Installs exact versions from package-lock.json

Why npm ci?

• Uses exact versions from package-lock.json
• Doesn't update package-lock.json
• Ensures reproducible builds
• Faster than npm install

Updating Packages

When you need to add or update packages:

Step 1: Add Package to package.json

# Find a version that's at least 2 weeks old
npm view <package-name> time

# Add exact version to package.json
"dependencies": {
  "new-package": "1.2.3"
}

Step 2: Verify Age

node scripts/check-package-age.js

Step 3: Update Lock File

cd frontend
npm install --package-lock-only

Step 4: Install and Test

npm ci
npm run build:prod

CI/CD Integration

Add the age check to your CI/CD pipeline:

GitLab CI Example

verify_package_age:
  stage: validate
  image: node:18-alpine
  script:
    - node scripts/check-package-age.js
  only:
    - merge_requests
    - main

GitHub Actions Example

- name: Check Package Age
  run: node scripts/check-package-age.js

Troubleshooting

"Package is too new" Error

If a package fails the age check:

1. Find an older version:

   npm view <package-name> versions --json
   npm view <package-name>@<older-version> time
   

2. Update package.json with older version

3. Re-run age check:

   node scripts/check-package-age.js
   

Can't Find Old Enough Version

If no version meets the 2-week requirement:

• Wait until the package is at least 2 weeks old
• Look for alternative packages
• Request an exception through your security team

Example Workflow

# 1. Check current package ages
node scripts/check-package-age.js

# 2. If all pass, install dependencies
cd frontend
npm ci

# 3. Build application
npm run build:prod

# 4. For air-gapped deployment
../scripts/build-for-airgap.sh

Scripts Reference

Script	Purpose
scripts/check-package-age.js	Verify all packages are ≥ 2 weeks old
scripts/pin-old-versions.sh	Helper script to validate and pin versions
scripts/build-for-airgap.sh	Build frontend for air-gapped deployment

Best Practices

1. Always commit package-lock.json

   • Ensures everyone uses the same versions
   • Required for reproducible builds

2. Use npm ci in CI/CD

   • Faster than npm install
   • Enforces lock file versions
   • Prevents surprises

3. Regular audits

   # Check for security vulnerabilities
   npm audit
   
   # Check package ages
   node scripts/check-package-age.js
   

4. Version ranges to avoid

   • ❌ ^1.2.3 (allows minor/patch updates)
   • ❌ ~1.2.3 (allows patch updates)
   • ❌ * or latest (allows any version)
   • ✅ 1.2.3 (exact version only)

Package Age Check Output

Checking package ages (must be at least 2 weeks old)...

✓ @angular/common@19.2.7 - 45 days old
✓ @angular/compiler@19.2.7 - 45 days old
✓ rxjs@7.8.0 - 180 days old
❌ new-package@1.0.0 - 5 days old (published 2025-01-12)

================================================================================

❌ FAILED: 1 package(s) are newer than 2 weeks:

  - new-package@1.0.0 (5 days old, published 2025-01-12)

Support

For questions or exceptions:

• Review with security team
• Document in project README
• Update this policy as needed