The npm worm is no longer hypothetical.

In the past nine months, the npm ecosystem has been hit by three of the most consequential supply-chain attacks in its history:

• Shai-Hulud — a self-replicating worm that compromised maintainer accounts via stolen tokens and CI secrets, then used those credentials to publish malicious versions of packages those maintainers owned. It hit ngx-bootstrap, tinycolor, and dozens of others before npm could contain it.
• TanStack npm packages compromised via the Shai-Hulud campaign — the same worm reaching deeper into the ecosystem, targeting one of the most-downloaded TypeScript ecosystems on the registry.
• Axios npm package compromise — a cross-platform RAT delivered through a single hijacked release, demonstrating how far a single compromised maintainer credential can travel through a package with hundreds of millions of weekly downloads.

The common thread in all three: attackers don’t need a zero-day, they need a postinstall hook and a few minutes before someone notices. Once a malicious release is live on the registry, every CI pipeline running npm install or pnpm install is a target. The window between publication and detection is the entire attack.

Your package manager’s config file is where you close that window. Not your linter, not your SBOM, not your audit pipeline — the .npmrc and pnpm-workspace.yaml sitting at the root of your repo. They decide whether your machine runs an attacker’s postinstall script, whether it accepts a hijacked release that’s three minutes old, whether it lets a transitive dep yank in code from a random GitHub URL.

This post is the config I’m now rolling out across all my own repos. Every directive carries its threat model in a comment, so a reader (or a future you) can tell what each line is actually defending against. Copy-paste-ready at the end.

The canonical reference for everything below is my npm Security Best Practices repo — it’s where these directives live as a curated, version-tracked source of truth. This post is the narrative companion: why each one matters, what attack it stops, and where the gotchas are.

The threat model in one paragraph

A malicious npm package can hurt you in four ways:

1. Install-time code execution via lifecycle scripts (preinstall, postinstall, etc.) that run during npm install without you ever importing the package.
2. A fresh malicious release — a hijacked maintainer account publishing a backdoored version that gets yanked within hours, but not before your CI pulls it.
3. Non-registry dependency sources — git+ssh://, tarball URLs, or GitHub shortcuts that bypass the registry’s signing, provenance, and yanking entirely.
4. Trust regression — a previously well-signed package suddenly publishing without provenance or trusted-publisher attestations, signaling an account takeover.

Every directive in the configs below targets one of these.

Hardening .npmrc

If your project uses npm directly, this file goes at the repo root:

# npm security best practices
# Source: https://github.com/lirantal/npm-security-best-practices
# SECURITY: do not run any lifecycle scripts (preinstall, install,
# postinstall, etc.) for dependencies. Postinstall scripts are the
# classic malware delivery vector — a transitive dep can execute
# arbitrary code on your machine during `npm install` without you
# ever running its code at runtime.
ignore-scripts=true
# SECURITY: reject git-source dependencies (git+ssh://, github:owner/repo,
# etc.). Git deps can ship their own .npmrc that overrides the path to
# the npm binary, achieving arbitrary code execution at install time —
# bypassing ignore-scripts entirely. This will be the default in npm 12.
allow-git=none
# SECURITY: refuse to install package versions younger than 30 days.
# Gives the community time to spot and yank hijacked releases before
# they reach your install. Value is in days.
min-release-age=30

Version floor

allow-git and min-release-age were both introduced in npm 11.10.0. Older versions silently ignore them. Pin your floor in package.json:

{
  "engines": {
    "npm": ">=11.10.0"
  }
}

Your own project’s engines is always enforced regardless of engine-strict, so this is sufficient to block installs on stale npm versions.

The allow-git detail that’s easy to miss

ignore-scripts=true is the well-known defense. What’s less appreciated: a git-source dependency can ship its own .npmrc that overrides the path npm uses to find its binary. That override fires before lifecycle scripts are even considered, so ignore-scripts doesn’t apply. allow-git=none is what plugs that hole. It will be the default in npm 12 — set it now and be forward-compatible.

For more on lifecycle-script defenses specifically, see NPM Ignore Scripts Best Practices.

Hardening pnpm-workspace.yaml

pnpm 10 added a more granular set of supply-chain controls than .npmrc exposes. If your project uses pnpm, this is the file:

# npm security best practices
# Source: https://github.com/lirantal/npm-security-best-practices
packages:
  - "packages/*"
# SECURITY: block packages newer than 30 days (43200 minutes).
# Gives the community time to spot and yank hijacked releases
# before they reach your install.
minimumReleaseAge: 43200
# SECURITY: reject a version whose publishing trust signals
# (npm provenance, trusted-publisher status, registry signatures)
# have regressed from prior releases. Catches account-takeover
# attacks where the attacker can't reproduce the legitimate CI
# pipeline that produced earlier provenance.
trustPolicy: no-downgrade
# Per-package or per-version exemptions for legitimate trust
# regressions (e.g. a maintainer who genuinely switched CI providers).
# Keep empty; add entries only with a written justification, and
# prefer a specific version range over allowing an entire package.
# Example:
# trustPolicyExclude:
#   - 'chokidar@4.0.3'
#   - 'webpack@4.47.0 || 5.102.1'
# Disabled intentionally. Skipping the trust check for older
# versions sounds useful for genuinely pre-provenance packages
# (npm provenance launched April 2023), but any value near
# minimumReleaseAge nullifies trustPolicy entirely — every
# installable version becomes exempt. Use trustPolicyExclude
# above for legitimate legacy cases instead.
# trustPolicyIgnoreAfter: 43200
# SECURITY: block install scripts by default; explicit allow-list
# only. Postinstall scripts are a primary malware delivery vector
# for transitive dependencies. Keep this list small and only
# enable packages whose postinstall is genuinely required.
allowBuilds:
  # Native bundler; postinstall fetches the platform-specific binary.
  esbuild: true
  # Native bundler; postinstall fetches the platform-specific binary.
  rolldown: true
  # Native module resolver used by some toolchains.
  unrs-resolver: true
# SECURITY: fail the install if a dependency wants to run a build
# script that isn't in the allow-list above. Without this, new
# postinstall scripts get silently skipped — you'd never know to
# audit them.
strictDepBuilds: true
# SECURITY: reject dependencies sourced from git URLs, tarball
# URLs, or local paths. These bypass registry signing, provenance,
# and yanking, and have been weaponized to deliver malware through
# innocent-looking transitive deps.
blockExoticSubdeps: true

If your repo is not a monorepo, omit the packages: block entirely — pnpm 10+ uses pnpm-workspace.yaml as the home of all config, not just workspace config.

Version floor

The highest individual floor among the active directives is blockExoticSubdeps, introduced in pnpm 10.26. Pin it:

{
  "engines": {
    "pnpm": ">=10.26"
  }
}

If you’re using corepack, you can pin exactly:

{
  "packageManager": "pnpm@10.26.0"
}

Note that pnpm 11 (released April 2026) makes minimumReleaseAge, strictDepBuilds, and blockExoticSubdeps defaults. If your team controls the pnpm version end-to-end, you can bump the floor to >=11 and let several of these directives become redundant — though leaving them explicit is harmless and self-documenting.

The trust-policy trap

The single subtlest gotcha in the pnpm config is the relationship between minimumReleaseAge and trustPolicyIgnoreAfter. The latter is a knob that says “skip the trust-policy check for versions older than N minutes” — useful in theory for genuinely pre-provenance packages (npm provenance launched April 2023, so most old releases lack it).

The trap: if you set trustPolicyIgnoreAfter to the same value as minimumReleaseAge (or even close to it), the two windows are exact complements. Every package eligible to install — by definition older than minimumReleaseAge — is automatically exempted from the trust check. trustPolicy: no-downgrade becomes a no-op for everything that actually reaches your node_modules.

The fix is to either set trustPolicyIgnoreAfter substantially higher than minimumReleaseAge (so the trust check has a real window to operate in), or to disable it entirely and rely on trustPolicyExclude for the rare legacy package that legitimately can’t satisfy the policy. The config above takes the second approach — simpler, harder to misconfigure.

What none of this protects against

A few honest disclaimers, because nobody benefits from oversold defenses:

• A malicious package already in your dependency tree. If you depend on lodash and someone hijacks the maintainer account today, none of these settings will rescue you on the next install of an existing version — they govern new installs, not what’s already in your node_modules from a prior install. Pair this config with a lockfile + npm ci / pnpm install --frozen-lockfile discipline.
• Runtime behavior. None of these settings inspect what the package does once it’s loaded. A package that lies dormant for weeks and then exfiltrates secrets at runtime is invisible to install-time policy.
• Direct code execution from your scripts. A malicious package.json script in your own repo (e.g., from a malicious PR) runs regardless of any of this. Code review of package.json changes is your defense there.

For deeper coverage of these adjacent gaps, see Liran’s Node.js Secure Coding materials and the post on how JavaScript developers should embrace npm security.

A recap for the actually-in-a-hurry reader

If you have five minutes, do this:

1. Copy the .npmrc or pnpm-workspace.yaml block above into the root of every repo you maintain.
2. Add engines.npm or engines.pnpm to each repo’s package.json to enforce the floor.
3. Commit. Open the PR. Merge. Repeat across your repo set — gh CLI’s Contents API makes this scriptable across hundreds of repos without ever cloning.
4. Watch the next supply-chain incident hit your feed and feel quietly fine about it.

The threat is no longer hypothetical, and the controls are no longer experimental. The Shai-Hulud worm and its descendants will keep finding new maintainers, new tokens, new packages. The point of these configs isn’t to predict the next attack — it’s to make sure that when one lands, your pnpm install simply refuses to bring it home.

Recommended further reading

Canonical reference:

• npm Security Best Practices — the curated repo behind every directive in this post.

Recent supply-chain incidents and analysis:

• Security Advisory for the Qix npm supply-chain compromise — affecting debug and the chalk ecosystem.
• The Shai-Hulud Attack: Post-Mortem, Best Practices, and Security Tools
• Shai-Hulud, Nx and even MCP malware in Supply Chain Attacks on the Node.js Ecosystem
• Supply Chain Security Campaigns on npm
• North Korea malware on npm and the Ledger Connect Kit crypto heist

Defensive practices:

• NPM Ignore Scripts Best Practices as Security Mitigation for Malicious Packages
• How JavaScript developers should embrace npm security
• How to use npm audit