UNPM

A secure npm wrapper that protects against supply chain attacks while maintaining full npm compatibility.

Why UNPM?

npm's default behavior allows packages to execute arbitrary scripts during installation, a vector exploited in numerous supply chain attacks. UNPM wraps npm commands and delegates to pnpm with security-first defaults:

• Scripts blocked by default - Dependency install scripts are blocked unless explicitly allowed
• Minimum release age - New packages must be at least 2 days old before installation
• Trust policy - Prevents version downgrades that could introduce malicious code
• Strict mode for CI - Enhanced protections for automated environments
• Package provenance - Verify supply chain integrity with attestation checks
• Gradual migration - Use npm and unpm interchangeably before committing to full migration
• Zero migration required - Same commands, same flags, drop-in replacement

Quick Start

Install

npm install -g @depgate/unpm

Requires pnpm (npm install -g pnpm).

Use

Replace npm with unpm:

unpm install              # Install dependencies
unpm add lodash           # Add a package
unpm run build            # Run scripts
unpm test                 # Run tests

That's it. Your project is now protected.

Key Features

Script Blocking

Install scripts from dependencies are blocked by default:

# If a package needs scripts, allow it explicitly
unpm allow-scripts add esbuild

Release Age Protection

Packages must be at least 2 days old, protecting against malicious packages being published and quickly installed:

# Override for a specific package if needed
unpm install --allow-recent=hotfix hotfix

Trust Policy

Prevents version downgrades that could introduce malicious code:

unpm install                    # Trust policy enabled by default
unpm install --no-trust-policy  # Disable if needed

Package Provenance

Verify supply chain integrity before installing:

unpm provenance lodash          # Check attestations and signatures
unpm prov [email protected]          # Alias with version

Strict Mode

For CI/CD, enable strict mode for maximum security:

UNPM_STRICT=true unpm ci
# or
unpm --strict ci

Strict mode enforces 7-day release age, blocks dlx, requires frozen lockfiles, and fails on unreviewed build scripts.

Gradual Migration

UNPM supports gradual migration from npm. Before running unpm migrate, npm and unpm work interchangeably:

# These can be used interchangeably before migration
npm install lodash
unpm install express    # Syncs with package-lock.json automatically
npm install axios       # Works seamlessly

When ready to fully commit to pnpm's security benefits:

unpm migrate

After migration, npm install/update is blocked to ensure consistent, secure dependency management.

Security Diagnostics

Check your project's security configuration:

unpm doctor --security

Reviews trust policy, release age settings, lockfile status, allowlist entries, and more.

Documentation

• Security Features - Script blocking, release age, strict mode
• Command Reference - All supported commands
• Configuration - Package.json and CLI options
• Migration Guide - Moving from npm to unpm
• Troubleshooting - Common issues and solutions

Requirements

• Node.js >= 18.0.0
• pnpm installed (npm install -g pnpm)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

Apache-2.0

Related Projects

• pnpm - Fast, disk space efficient package manager
• LavaMoat - Tools for sandboxing JavaScript dependency risk