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:

```json
{
  "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:

```bash
# 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`:**

```bash
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

```bash
# 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

```bash
node scripts/check-package-age.js
```

### Step 3: Update Lock File

```bash
cd frontend
npm install --package-lock-only
```

### Step 4: Install and Test

```bash
npm ci
npm run build:prod
```

## CI/CD Integration

Add the age check to your CI/CD pipeline:

### GitLab CI Example

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

### GitHub Actions Example

```yaml
- 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:**
   ```bash
   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:**
   ```bash
   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

```bash
# 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**
   ```bash
   # 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