[RFC] Make install scripts opt-in

[JamieMagee]

Summary

Block dependency install scripts (preinstall, install, postinstall, and auto-detected node-gyp builds) by default during npm install. Projects opt in to running scripts for specific dependencies via a new allowScripts field in package.json. Two new CLI commands, npm approve-scripts and npm deny-scripts, help users build and maintain the allowlist.

npm is the only remaining major package manager that runs dependency install scripts by default. pnpm v10+, Yarn Berry, Bun, and Deno all block them.

Why now

Recent attacks:

• Shai-Hulud worm (September 2025): self-replicating postinstall payload compromised 500+ npm packages by stealing maintainer tokens and republishing infected versions.
• chalk, debug, and 17 other packages (September 2025): phished maintainer account used to inject Web3 wallet-draining code into packages with over 2B combined weekly downloads. Delivered via postinstall.
• Axios (March 2026): hijacked lead maintainer published versions with a phantom dependency that existed only to trigger its postinstall hook, deploying a cross-platform RAT. The malicious package was never imported in Axios source code.

Install scripts run automatically the moment a package lands in the dependency tree. They don't require any require() or import from the application. A typo, a transitive dep change in a lockfile a reviewer didn't read, or a maintainer compromise becomes immediate code execution.

Relationship to other RFCs

• Supersedes RFC #488 (the 2021 ancestor, 369 👍, rejected as too disruptive at the time). The phased migration plan in this RFC addresses that concern directly.
• Supersedes RFC #861 per author's note.

[brunoborges]

I'm sure this was considered by the team, but it would be great if they can provide insights: what is the rationale for keeping install scripts feature in the first place? In other words: why not get rid of this feature completely?

[leobalter]

@brunoborges The short answer is that a small but legitimate tail of packages still relies on install scripts (canvas, sharp, sqlite3, and similar native addons), and --ignore-scripts today is all-or-nothing, which is why it isn't a practical substitute.

The ecosystem has largely shifted to prebuilt binaries via optionalDependencies (esbuild, SWC, Sharp, Rollup, Biome, etc.), so the remaining surface is small - but it's non-zero, and removing the feature would break those packages with no clean migration path.

The actual problem isn't that the feature exists, it's arbitrary execution from unaudited transitive deps, and that's addressable by making scripts opt-in with an explicit per-package allowlist. That's the direction this RFC takes, and it leaves room to tighten further in future majors.

[brunoborges]

@leobalter I am afraid the RFC does not address the root of the problem that libraries are allowed to have install scripts in the first place. It still leaves room for laziness as an attack vector.

The actual problem isn't that the feature exists, it's arbitrary execution from unaudited transitive deps, and that's addressable by making scripts opt-in with an explicit per-package allowlist.

I'd argue that the existence of the feature is the actual problem. Once the feature exists, any enhancement is an additional guardrail.

One approach to consider is to distinguish between executable tools and libraries as published packages.

[AllanOricil]

It would also be useful if --ignore-scripts combined with --verbose displayed the exact lifecycle scripts that would have been executed, including their resolved paths (real ones not symlinks) and content hashes.

With this output we can then edit the new --allowScripts flag with the exact output showed, including its sha, instead of just the package name

"allowScripts" : [
    "path/to/script.extension?sha256=foo"
]

The current allowScripts proposal is still too permissive if approvals are scoped only to package names.

A package can change its lifecycle scripts between versions — or even within the same version range — which means the developer may end up executing code that was never actually reviewed or approved.

Because of that, approvals should be bound to the exact script file being executed, not just the package identity.

[JamieMagee]

It would also be useful if --ignore-scripts combined with --verbose displayed the exact lifecycle scripts that would have been executed, including their resolved paths (real ones not symlinks) and content hashes.

@AllanOricil I like this idea, but I think it's orthogonal to the rest of your proposal. A dry-run view of "here's what would actually run, with paths resolved through symlinks" is a useful diagnostic on its own, however approvals end up scoped. Worth its own RFC IMO.

With this output we can then edit the new --allowScripts flag with the exact output showed, including its sha, instead of just the package name

"allowScripts" : [
    "path/to/script.extension?sha256=foo"
]

The part I'm not sold on is hashing the script file itself. Lifecycle script values in package.json aren't file paths, they're shell command strings. A real postinstall looks like node scripts/setup.js && chmod +x ./bin/*. To meaningfully hash "what's about to run" you'd have to resolve every binary referenced on PATH, hash the transitive JS closure reachable from the entry script, and re-hash any time the Node.js or toolchain version changes. So every dependency update forces a full re-review of every script. In practice that's the dependency-approval equivalent of a default-deny TOFU prompt; people click through, and the signal disappears.

The current allowScripts proposal is still too permissive if approvals are scoped only to package names.

Agreed when it's name-only. The RFC's answer is that you can pin a version: "allowScripts": { "esbuild@0.20.0": true } only approves that exact version. Bumping to 0.20.1 puts esbuild back in npm approve-scripts --pending. The name-only form is there for convenience on packages whose install scripts you genuinely don't care to gate per-version.

A package can change its lifecycle scripts between versions — or even within the same version range — which means the developer may end up executing code that was never actually reviewed or approved.

Pinned entries handle the version-to-version case, range keys like ^0.20.0 are rejected, and same-version byte changes are caught by the lockfile's SHA-512 integrity.

Because of that, approvals should be bound to the exact script file being executed, not just the package identity.

name@version + lockfile integrity already binds approvals to the exact bytes. Per-script hashing only helps if integrity is wrong. Do you have a concrete attack in mind that name-plus-version-plus-integrity misses?

[JamieMagee]

There's a Phase 1 implementation up at npm/cli#9360 for anyone who wants to look at it alongside the RFC.

It's advisory-only. Scripts still run, but install ends with a grouped warning listing packages whose install scripts haven't been approved via allowScripts. The matcher, the approve-scripts / deny-scripts commands, policy layering, and the three new configs are all wired in. The arb.rebuild() gate is what Phase 2 will flip.

Reviews on either thread welcome.

[sheplu]

+1 on having something around that
do you want to include part of this RFC something similar for the allow-git config?

[AllanOricil]

@JamieMagee One case I was thinking about that name@version + lock file integrity does not fully cover is when lifecycle scripts fetch remote content dynamically.

For example, a postinstall script may download an executable from a stable URL:

{
  "postinstall": "node scripts/install.js"
}

where install.js does something like:

https.get("https://example.com/tool/latest")

In that scenario:

• the package version remains unchanged,
• the lockfile integrity remains valid,
  but the actual executed payload can still change server-side at any time.

So name@version + integrity guarantees the integrity of the npm package itself, but not necessarily the integrity of the code ultimately executed during install.

That is partly why I was thinking about approvals at the executable/script level rather than only at the package level, although I agree it still would not completely solve dynamic remote execution.

[AllanOricil]

I will open a RFC for the other idea of outputing the list of all lifecycle scripts that would have run, if that isn't shown already. Maybe that info should be displayed as a warning, in a parsable way. We could use the output to manually analyze each executable or use a consensus of many LLMs analysis to better warn developers.

Maybe NPM should do this LLM analysis at publish time before making a package available?

[AllanOricil]

@JamieMagee can you enforce the approval of a script to be required at least once per host? I don't want Dev B to blindly accept Dev's A trust policy when he never touched the codebase, specially because of dynamic scripts that can bypass integrity hashes. For example, given a list of allowScripts, each script listed will require a review and approval on every new host before it can ever be executed. Could map host approval/acknowledgement to package, version and integrity and read/write it from ~/.npm ?

[bakkot]

@AllanOricil You seem to want this to be addressing a threat model it's just not for. This is about addressing the case where one of your transitive dependencies is compromised and a malicious build script is added, a situation we have seen several times recently. It is not and should not be about addressing threats from other maintainers of a package you're building.

[AllanOricil]

It is not and should not be about addressing threats from other maintainers of a package you're building.

That's a fair read of what I wrote — my framing wasn't clear. But it's not what I meant. I'm not talking about maintainers of my own package, and I'm not distrusting a specific person.

The concern is that allowScripts turns one developer's review decision about a transitive dependency's script into a committed artifact everyone inherits. Reviews are fallible. A developer can approve a script by mistake — for example, allowlisting one whose install step fetches and runs code from a remote server, without realizing that makes it a live compromise vector. Once that approval is in allowScripts, every colleague who clones and installs runs that script on the strength of a single, possibly-mistaken review — including after the original reviewer has left the org.

So this is inside the compromised-transitive-dependency model you described, not outside it. allowScripts defends against that case by relying on human review to decide which scripts are safe. My point is that human review is fallible, and the proposal propagates one person's review — mistakes included — to the whole org without anyone else looking.

The mitigation: require each host to review each allowlisted script at least once before it runs there (acknowledgment keyed to package + version + integrity, stored in ~/.npm). A single reviewer's mistake then isn't silently inherited — each developer gets a chance to catch it, the way independent review catches errors one reviewer misses. It doesn't make any individual review infallible; it stops one fallible review from becoming an org-wide fact.

If this is better as a follow-up RFC than in scope here, that's a fine answer — I wanted it clear it's a supply-chain concern about inherited, fallible review, not a complaint about any maintainer.

[bakkot]

In order for one developer's decision to allowlist a script to affect another, it must be committed and pushed to a shared package.json. Teams which care about security are going to require a different person to review that before it lands. So it will not be relying on a single person unless your team is already in the habit of landing unreviewed changes or approving changes without actually reviewing them, in which case forcing every member of the team to personally approve everything in allowScripts will not save you.

[AllanOricil]

Teams which care about security are going to require a different person to review that before it lands. So it will not be relying on a single person unless your team is already in the habit of landing unreviewed changes or approving changes without actually reviewing them, in which case forcing every member of the team to personally approve everything in allowScripts will not save you.

Fair — PR review does add a second reviewer. On a team that requires it, the allowScripts change gets reviewed before it lands, so I'll drop the "single reviewer" framing.

But there's a population PR review doesn't reach at all: everyone who clones an open-source project and runs npm install. Contributors, people building from source, downstream projects, forks — none of them took part in the maintainer's review. They inherit the maintainer's allowScripts decision without ever seeing it.

That's where this stops being a team-trust question. For a public repo, three things line up:

• the allowScripts list is committed and public, so an attacker can read exactly which scripts every cloner will run;
• if one of those scripts is dynamic — fetches and executes remote code — its payload can change server-side, with no version bump, no integrity change, nothing for PR review or the lockfile to catch;
• everyone who builds the project after that change runs the new payload, on a review they never made.

So a popular project's public allowScripts becomes a targeting list: compromise one listed package's remote payload, hit everyone who builds the project. And the timeline is the whole problem — the review happens at time T, when the script is benign; the payload turns malicious at T+N; everyone who builds between T+N and the day someone finally notices runs the compromised payload, on a review made before the threat existed. PR review is point-in-time: it covers T, not T+N, and it never involved the cloners at all.

To be clear about what I'm not claiming: this isn't allowScripts making things worse than today — today those scripts run on every clone with no review at all. The point is that allowScripts records trust in a package's identity (version + integrity), while the risk lives in behavior the reviewer couldn't see and the cloner never reviewed. Another approval step doesn't change that; surfacing what the script does — e.g. "this fetches and executes remote code" — at the point it would run at least lets someone decline the pattern.

Probably its own follow-up rather than in scope here, but it's why I don't think identity-based approval is sufficient on its own.

[bakkot]

All review is point in time. If your threat model includes install scripts changing behavior after review, requiring each person to review makes little difference. The compromise could just as well happen after any given person has already reviewed. And surfacing information like whether a script is fetching remote code - given that many scripts are running arbitrary shell commands anyway - is not feasible without completely redoing how scripts execute.

This conversation really gives me the feeling of arguing with someone who is just copy pasting LLM output. Regardless of whether that's true I don't think it will be productive for me to continue discussing this with you so I'm not going to respond further.

[AllanOricil]

This conversation really gives me the feeling of arguing with someone who is just copy pasting LLM output. Regardless of whether that's true I don't think it will be productive for me to continue discussing this with you so I'm not going to respond further.

Calling my argument LLM output is a convenient ad hominem exit, but the threat model is real. "Stale trust" when developers leave a company is a massive enterprise security risk. But since you've checked out, let's leave it there.

[BrunoBernardino]

@AllanOricil I'm nobody, but I think your request makes sense as a separate RFC, since this is focusing on the described threat model which is a subset of what seems to be yours, and this one would already be an amazing improvement to npm. It definitely feels like "scope creep" to me, even if it's a valid concern and security improvement.

[owlstronaut]

Moderation note: I've removed a comment in this thread for tone. The substantive concerns about stale trust and dynamic-fetch payloads are real and worth pursuing, and the community is welcome to open an RFC for further discussion of that. For this RFC, let's keep discussion focused on the mechanism's herein and civil per the Code of Conduct

[manzoorwanijk]

IMHO the syntax here is brought in from pnpm approve-builds, and we should probably use what npm uses already.
So it could be npm scripts approve and npm scripts deny, which matches other npm commands like npm teams <subcommand>, and npm cache <subcommand>.

That way the docs reference stays on a single page, and those are not two different commands.

[owlstronaut]

This is a good point, while the inverse commands aren't totally unprecedented here either. I'm landing what we have for phase 1 now. I think we could consider making the approve-scripts and deny-scripts aliases and add the scripts namespace for phase 2. @JamieMagee do you haver a gut reaction?

[JamieMagee]

Yeah, I mention it in various places throughout the RFC that pnpm was inspiration for the design of this functionality. I can certainly implement more npm-like commands (npm scripts approve and npm scripts deny) alongside the existing proposals (npm approve-scripts and npm deny-scripts).

[manzoorwanijk]

Yes, I also did the same for native dependency patching proposal - #862 and then updated it to use npm style sub command approach.

I think once we ship this feature, it’s probably time to handle #862 😁

[JamieMagee]

I've had a little time to think on this more, and my worry is that an npm scripts command may be confused with the scripts block in package.json. They do related, but different, things.

[manzoorwanijk]

--ignore-scripts is similar too, and I think that is fine.

[manzoorwanijk]

But I think instead of npm scripts, we could call it npm trust, with subcommands like

• npm trust add lefthook
• npm trust rm lefthook
• npm trust ls
• npm trust clear

Other candidates are

• npm install-scripts
  • npm install-scripts approve lefthook
  • npm install-scripts deny lefthook
  • npm install-scripts ls
• npm hooks
• npm lifecycle

[bakkot]

I like npm install-scripts. A tiny bit more verbose, but it's much clearer.

[JamieMagee]

Phase 1 has been completed and published 🎉

• https://github.com/npm/cli/releases/tag/v11.16.0
• https://www.npmjs.com/package/npm/v/11.16.0

[everett1992]

I was thinking more about bundled dependencies. I know the code base I manage has a few instances of packages that depend on bundlers that have scripts. These instances won't be able to use strict-allow-scripts because the unreviewed (unreviewable) bundled dependency will fail.

What do you think about approvals for the bundler to apply to the bundled dependencies?

"allowScripts": {
  "a-builder@1.0.0": true,
},
"dependencies": {
  "a-builder": "^1.0.0"
}

all scripts in packages bundled by the approved a-builder are allowed to run.

• When a package@version is approved we're protected by integrity / immutability. a-bundler can't add new dependencies with scripts, so we've approved an explicit set
• If a whole package name is approved there are more risks, an update could pull in compromised packages,
  you're not only exposed to the approved package being compromised.

I'm still happy with the RFC and deferring this for a followup.

[everett1992]

Bundled dependencies are also the packages that will be included in a packages own tarball when published.

I can see two ways to address those:

• Do not allow those scripts to be allowlisted, because consumers would not be able to allowlist them. Make that explicit in the errors.
• Allow the package to approve the scripts, the trust issues outlined here don't apply, these packages were fetched from the registry.

I think the phase-1 implemenation merged into latest doesn't distinguish between packages that were bundled and packages that will be bundled.