feat: Phase 1 of allowScripts opt-in install-script policy

[JamieMagee]

Implements Phase 1 of npm/rfcs#868, which makes dependency install scripts opt-in.

Install behaviour is unchanged. Scripts still run as they always have. The only Phase 1 user-visible change is one advisory block at the end of npm install listing packages whose install scripts haven't been reviewed via the new allowScripts field in package.json. A future release will turn that advisory into an actual block.

What landed

• allowScripts field in package.json, read at install time
• Three new configs: allow-scripts, strict-script-builds, dangerously-allow-all-scripts. The latter two are no-ops in this release. They're registered so projects can pin them in tooling ahead of the release that flips the default.
• npm approve-scripts and npm deny-scripts commands, with the RFC's asymmetric pin rule (approves can pin, denies are always name-only)
• Advisory warning during npm install, ci, update, and rebuild. npm exec / npx consult only the user/global .npmrc layer per the RFC, with the policy threaded through libnpmexec for Phase 2 enforcement.
• Identity matcher in @npmcli/arborist covering registry, git, file, and remote tarballs. Registry identity is derived from the lockfile's resolved URL (via versionFromTgz), never from node.packageName or node.version. Those getters read the installed tarball's package.json and can be forged.
• Aliases match against the underlying registered package, not the alias name. trusted@npm:naughty@1.0.0 is approved by writing naughty, not trusted. Holds even under omitLockfileRegistryResolved, where the install location alone (node_modules/trusted) would be misleading. The underlying name is derived from the incoming edge's alias subSpec.
• Bundled deps with install scripts are flagged as unreviewed and filtered out of npm approve-scripts --all and positional matches. Per RFC they cannot be allowlisted in Phase 1.
• Warning when a non-root workspace declares its own allowScripts

What's deliberately deferred

• Actual blocking. The matcher exists and the policy is threaded through to arborist, but arb.rebuild()'s build set still runs everything. Phase 2 will gate #addToBuildSet on the matcher.
• A safe allowlist syntax for bundled deps. The RFC notes a candidate parent@1.2.3 > bundled-name form for a follow-up.

Refs: npm/rfcs#868

[bakkot]

I think it would be bad to support an allowScripts field which can contain "foo": false but still allow foo's scripts to run. Similarly I think it would be bad to include a no-op strict-script-builds. That looks like it provides protection, but doesn't.

Also, it's weird to print this advisory information without it being actionable (except by silencing the warning).

I think a better phasing would be to implement the full RFC except that the default for packages not explicitly listed is to allow with warning, rather than to deny with warning, and then a later release can make the default to deny with warning and make no other changes.

If you really don't want to implement blocking in the first phase, it would be better for it to be a hard error to have "foo": false in allowScripts.

Three new configs: allow-scripts, strict-script-builds, dangerously-allow-all-scripts.

Why is the --allow-scripts CLI flag necessary? I feel like that's just going to encourage people to say "install this with npm install foo --allow-scripts=foo" and then it will work on their machine but not for the next person who tries to build the package.

Also, sidebar, the naming of strict-script-builds and dangerously-allow-all-scripts is weird. I would expect those to be named similarly, or possibly be the same option (--enforce-allow-scripts=on vs --enforce-allow-scripts=dangerously-off, maybe).

[JamieMagee]

@bakkot Yeah, all of that sounds good. I'll switch to your proposed phasing.

Concretely:

• Actual enforcement goes in. true allows, false blocks, both do what the user expects.
• Phase 1 default for unlisted packages stays "allow with warning", which keeps the RFC's promise that nothing changes for anyone who hasn't opted in. Phase 2 is then the default flip.
• Renaming --strict-script-builds to --strict-allow-scripts. --dangerously-allow-all-scripts keeps its name. I'd rather have a long, ugly, obviously discouraged flag than collapse it into a ternary.
• Going to tighten the --allow-scripts description too, calling out that it's for one-off / npx use and that team-wide policy belongs in package.json or .npmrc. Doesn't remove the footgun but at least doesn't lean into it.

The reason I shipped advisory-only originally was to keep the "install behaviour unchanged" promise in the RFC. Your phasing keeps that for everyone who doesn't write a false entry, and anyone who does is opting in deliberately. Better than what I had.

Going to amend the RFC for the new phasing and update the PR description here.

[bakkot]

SGTM.

Renaming --strict-script-builds to --strict-allow-scripts. --dangerously-allow-all-scripts keeps its name. I'd rather have a long, ugly, obviously discouraged flag than collapse it into a ternary.

I don't feel strongly about this point, but fwiw --enforce-allow-scripts=dangerously-off is in fact longer and more ugly than --dangerously-allow-all-scripts, and is at least as obviously discouraged to my eye.

That said, it's true that there are two dangerous things (the [new] phase 1 default, and disabled entirely), and naming both would be a little awkward. Best I've got is --enforce-allow-scripts=dangerously-allow-missing and --enforce-allow-scripts=dangerously-off respectively.

[everett1992]

I know I'm in the minority but I use a custom registry that doesn't host tarballs at the 'standard' tarball URL (/@foo/bar/-/bar-1.2.3.tgz or /foo/-/foo-1.2.3.tgz). Those paths aren't really a requirement of npm registry, since the model is to read from dist.tarball. This function doesn't return the correct version for URLs my mirror uses, which means all name@version patterns don't match.

Is there a way we could implement without parsing the URL?

• There's the arborist edges, that define 'why' it was fetched
• There could be some meta-resolved 'source' field derived from the resolved version?

[owlstronaut]

I think this is a fair concern. So your name only version will work, but the pinned version doesn't? I think for this PR that will be scope creep and it is in a good and useful state now, but if you'd like to follow up with a pr that addresses pinned approvals for non-standard registry URLs, I'd happily review it. the constraint is that whatever new trust anchor we pick has to keep holding under loadActual() so a forged on-disk package.json can't override it.

[github-actions]

⚠️ Backport to release/v11 failed.

This usually means the cherry-pick had conflicts. Please create a manual backport:

git fetch origin release/v11
git checkout -b backport/v11/9360 origin/release/v11
git cherry-pick -x 7068d4286eb446fdb0ded08d15d7b5c3883d80f5
# resolve any conflicts, then:
git push origin backport/v11/9360

Error details

Command failed: git cherry-pick -x 7068d4286eb446fdb0ded08d15d7b5c3883d80f5
error: could not apply 7068d4286... feat: Phase 1 of `allowScripts` opt-in install-script policy (#9360)
hint: After resolving the conflicts, mark them with
hint: "git add/rm <pathspec>", then run
hint: "git cherry-pick --continue".
hint: You can instead skip this commit with "git cherry-pick --skip".
hint: To abort and get back to the state before "git cherry-pick",
hint: run "git cherry-pick --abort".
hint: Disable this message with "git config set advice.mergeConflict false"