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

docs/lib/content/commands/npm-approve-scripts.md

@@ -0,0 +1,73 @@
+---
+title: npm-approve-scripts
+section: 1
+description: Approve install scripts for specific dependencies
+---
+
+### Synopsis
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS -->
+
+### Description
+
+Manages the `allowScripts` field in your project's `package.json`, which
+records which of your dependencies are permitted to run install scripts
+(`preinstall`, `install`, `postinstall`, and `prepare` for non-registry
+sources). This command is the recommended way to maintain that field.
+
+In the current release, this field is advisory: install scripts still run
+by default, but installs print a list of packages whose scripts have not
+been reviewed. A future release will block unreviewed install scripts.
+
+There are three modes:
+
+```bash
+npm approve-scripts <pkg> [<pkg> ...]
+npm approve-scripts --all
+npm approve-scripts --allow-scripts-pending
+```
+
+`<pkg>` matches every installed version of that package. By default the
+command writes pinned entries (`pkg@1.2.3`), which keep their approval
+narrowed to the specific version you reviewed. Pass `--no-allow-scripts-pin` to write
+name-only entries that allow any future version.
+
+`--all` approves every package with unreviewed install scripts in one go.
+
+`--allow-scripts-pending` is read-only: it lists every package whose install scripts
+are not yet covered by `allowScripts`, without modifying `package.json`.
+
+`approve-scripts` honours the asymmetric pin rule: if you re-approve a
+package whose installed version has changed, the existing pin is rewritten
+to track the new installed version. Multi-version statements
+(`pkg@1 || 2`) are left alone, since they likely capture intent that
+the command cannot infer. Existing `false` entries always win;
+`approve-scripts` will not silently re-allow a package you previously
+denied.
+
+### Examples
+
+```bash
+# Approve all currently-installed install scripts after reviewing them
+npm approve-scripts --all
+
+# Approve specific packages, pinned to their installed version
+npm approve-scripts canvas sharp
+
+# Approve name-only (any version of this package is allowed)
+npm approve-scripts --no-allow-scripts-pin canvas
+
+# Preview which packages still need review
+npm approve-scripts --allow-scripts-pending
+```
+
+### Configuration
+
+<!-- AUTOGENERATED CONFIG DESCRIPTIONS -->
+
+### See Also
+
+* [npm deny-scripts](/commands/npm-deny-scripts)
+* [npm install](/commands/npm-install)
+* [npm rebuild](/commands/npm-rebuild)
+* [package.json](/configuring-npm/package-json)

docs/lib/content/commands/npm-deny-scripts.md

@@ -0,0 +1,58 @@
+---
+title: npm-deny-scripts
+section: 1
+description: Deny install scripts for specific dependencies
+---
+
+### Synopsis
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS -->
+
+### Description
+
+The companion command to [`npm approve-scripts`](/commands/npm-approve-scripts).
+Writes `false` entries into the `allowScripts` field of your project's
+`package.json`, recording that a dependency must not run install scripts
+even if a future version would otherwise be eligible.
+
+In the current release, install scripts still run by default, so `deny-scripts`
+only affects how installs of denied packages are reported. A future release
+will block unreviewed install scripts and respect deny entries at install
+time.
+
+```bash
+npm deny-scripts <pkg> [<pkg> ...]
+npm deny-scripts --all
+```
+
+`<pkg>` matches every installed version of that package. Denies are always
+written name-only (`"pkg": false`), regardless of `--allow-scripts-pin`. Pinning a deny
+to a specific version would silently re-allow scripts for any other version
+of the same package, which defeats the purpose; the command picks the
+safer default for you.
+
+`--all` denies every package with unreviewed install scripts.
+
+If a `true` (pinned or name-only) entry exists for a package and you then
+deny it, the existing allow entries are removed so the name-only deny is
+unambiguous.
+
+### Examples
+
+```bash
+# Deny a specific package outright
+npm deny-scripts telemetry-pkg
+
+# Deny everything that has install scripts and isn't already approved
+npm deny-scripts --all
+```
+
+### Configuration
+
+<!-- AUTOGENERATED CONFIG DESCRIPTIONS -->
+
+### See Also
+
+* [npm approve-scripts](/commands/npm-approve-scripts)
+* [npm install](/commands/npm-install)
+* [package.json](/configuring-npm/package-json)

docs/lib/content/nav.yml

@@ -12,6 +12,9 @@
   - title: npm access
     url: /commands/npm-access
     description: Set access level on published packages
+  - title: npm approve-scripts
+    url: /commands/npm-approve-scripts
+    description: Approve install scripts for specific dependencies
   - title: npm audit
     url: /commands/npm-audit
     description: Run a security audit
@@ -33,6 +36,9 @@
   - title: npm dedupe
     url: /commands/npm-dedupe
     description: Reduce duplication in the package tree
+  - title: npm deny-scripts
+    url: /commands/npm-deny-scripts
+    description: Deny install scripts for specific dependencies
   - title: npm deprecate
     url: /commands/npm-deprecate
     description: Deprecate a version of a package

lib/commands/approve-scripts.js

@@ -0,0 +1,10 @@
+const AllowScriptsCmd = require('../utils/allow-scripts-cmd.js')
+
+class ApproveScripts extends AllowScriptsCmd {
+  static description = 'Approve install scripts for specific dependencies'
+  static name = 'approve-scripts'
+  static usage = ['<pkg> [<pkg> ...]', '--all', '--allow-scripts-pending']
+  static verb = 'approve'
+}
+
+module.exports = ApproveScripts

lib/commands/ci.js

@@ -1,4 +1,6 @@
 const reifyFinish = require('../utils/reify-finish.js')
+const resolveAllowScripts = require('../utils/resolve-allow-scripts.js')
+const strictAllowScriptsPreflight = require('../utils/strict-allow-scripts-preflight.js')
 const runScript = require('@npmcli/run-script')
 const fs = require('node:fs/promises')
 const path = require('node:path')
@@ -25,6 +27,9 @@ class CI extends ArboristWorkspaceCmd {
     'allow-file',
     'allow-git',
     'allow-remote',
+    'allow-scripts',
+    'strict-allow-scripts',
+    'dangerously-allow-all-scripts',
     'audit',
     'bin-links',
     'fund',
@@ -43,12 +48,14 @@ class CI extends ArboristWorkspaceCmd {
     const ignoreScripts = this.npm.config.get('ignore-scripts')
     const where = this.npm.prefix
     const Arborist = require('@npmcli/arborist')
+    const { policy: allowScriptsPolicy } = await resolveAllowScripts(this.npm)
     const opts = {
       ...this.npm.flatOptions,
       packageLock: true, // npm ci should never skip lock files
       path: where,
       save: false, // npm ci should never modify the lockfile or package.json
       workspaces: this.workspaceNames,
+      allowScripts: allowScriptsPolicy,
     }
 
     // generate an inventory from the virtual tree in the lockfile
@@ -69,6 +76,7 @@ class CI extends ArboristWorkspaceCmd {
     // We need a new one because the virtual tree from the lockfile can have extraneous dependencies in it that won't install on this platform
     const arb = new Arborist(opts)
     await arb.buildIdealTree()
+    await strictAllowScriptsPreflight({ arb, npm: this.npm, idealTreeOpts: opts })
 
     // Verifies that the packages from the ideal tree will match the same versions that are present in the virtual tree (lock file).
     const errors = validateLockfile(virtualInventory, arb.idealTree.inventory)

lib/commands/deny-scripts.js

@@ -0,0 +1,10 @@
+const AllowScriptsCmd = require('../utils/allow-scripts-cmd.js')
+
+class DenyScripts extends AllowScriptsCmd {
+  static description = 'Deny install scripts for specific dependencies'
+  static name = 'deny-scripts'
+  static usage = ['<pkg> [<pkg> ...]', '--all']
+  static verb = 'deny'
+}
+
+module.exports = DenyScripts

lib/commands/exec.js

@@ -1,5 +1,6 @@
 const { resolve } = require('node:path')
 const libexec = require('libnpmexec')
+const resolveAllowScripts = require('../utils/resolve-allow-scripts.js')
 const BaseCommand = require('../base-cmd.js')
 
 class Exec extends BaseCommand {
@@ -10,6 +11,9 @@ class Exec extends BaseCommand {
     'workspace',
     'workspaces',
     'include-workspace-root',
+    'allow-scripts',
+    'strict-allow-scripts',
+    'dangerously-allow-all-scripts',
   ]
 
   static name = 'exec'
@@ -74,8 +78,16 @@ class Exec extends BaseCommand {
       throw this.usageError()
     }
 
+    // Resolve the install-script policy from the user/global .npmrc layer
+    // only. The RFC requires exec/npx to ignore any project
+    // package.json#allowScripts; CLI flags still apply.
+    const { policy: allowScriptsPolicy } = await resolveAllowScripts(this.npm, {
+      skipProjectConfig: true,
+    })
+
     return libexec({
       ...flatOptions,
+      allowScripts: allowScriptsPolicy,
       // we explicitly set packageLockOnly to false because if it's true when we try to install a missing package, we won't actually install it
       packageLockOnly: false,
       // what the user asked to run args[0] is run by default

lib/commands/install.js

@@ -5,6 +5,8 @@ const runScript = require('@npmcli/run-script')
 const pacote = require('pacote')
 const checks = require('npm-install-checks')
 const reifyFinish = require('../utils/reify-finish.js')
+const resolveAllowScripts = require('../utils/resolve-allow-scripts.js')
+const strictAllowScriptsPreflight = require('../utils/strict-allow-scripts-preflight.js')
 const ArboristWorkspaceCmd = require('../arborist-cmd.js')
 
 class Install extends ArboristWorkspaceCmd {
@@ -31,6 +33,9 @@ class Install extends ArboristWorkspaceCmd {
     'allow-file',
     'allow-git',
     'allow-remote',
+    'allow-scripts',
+    'strict-allow-scripts',
+    'dangerously-allow-all-scripts',
     'audit',
     'before',
     'min-release-age',
@@ -138,14 +143,17 @@ class Install extends ArboristWorkspaceCmd {
     }
 
     const Arborist = require('@npmcli/arborist')
+    const { policy: allowScriptsPolicy } = await resolveAllowScripts(this.npm)
     const opts = {
       ...this.npm.flatOptions,
       auditLevel: null,
       path: where,
       add: args,
       workspaces: this.workspaceNames,
+      allowScripts: allowScriptsPolicy,
     }
     const arb = new Arborist(opts)
+    await strictAllowScriptsPreflight({ arb, npm: this.npm, idealTreeOpts: opts })
     await arb.reify(opts)
 
     if (!args.length && !isGlobalInstall && !ignoreScripts) {

lib/commands/rebuild.js

@@ -1,8 +1,11 @@
 const { resolve } = require('node:path')
-const { output } = require('proc-log')
+const { log, output } = require('proc-log')
 const npa = require('npm-package-arg')
 const semver = require('semver')
 const ArboristWorkspaceCmd = require('../arborist-cmd.js')
+const checkAllowScripts = require('../utils/check-allow-scripts.js')
+const resolveAllowScripts = require('../utils/resolve-allow-scripts.js')
+const strictAllowScriptsPreflight = require('../utils/strict-allow-scripts-preflight.js')
 
 class Rebuild extends ArboristWorkspaceCmd {
   static description = 'Rebuild a package'
@@ -12,6 +15,9 @@ class Rebuild extends ArboristWorkspaceCmd {
     'bin-links',
     'foreground-scripts',
     'ignore-scripts',
+    'allow-scripts',
+    'strict-allow-scripts',
+    'dangerously-allow-all-scripts',
     ...super.params,
   ]
 
@@ -26,9 +32,11 @@ class Rebuild extends ArboristWorkspaceCmd {
     const globalTop = resolve(this.npm.globalDir, '..')
     const where = this.npm.global ? globalTop : this.npm.prefix
     const Arborist = require('@npmcli/arborist')
+    const { policy: allowScriptsPolicy } = await resolveAllowScripts(this.npm)
     const arb = new Arborist({
       ...this.npm.flatOptions,
       path: where,
+      allowScripts: allowScriptsPolicy,
       // TODO when extending ReifyCmd
       // workspaces: this.workspaceNames,
     })
@@ -50,11 +58,28 @@ class Rebuild extends ArboristWorkspaceCmd {
       })
       const nodes = tree.inventory.filter(node => this.isNode(specs, node))
 
+      await strictAllowScriptsPreflight({ arb, npm: this.npm })
       await arb.rebuild({ nodes })
     } else {
+      await arb.loadActual()
+      await strictAllowScriptsPreflight({ arb, npm: this.npm })
       await arb.rebuild()
     }
 
+    // Phase 1 advisory: list any packages whose install scripts ran (or
+    // would have run) and are not yet covered by allowScripts. Rebuild
+    // doesn't go through reifyFinish, so the walker is invoked here.
+    const unreviewed = await checkAllowScripts({ arb, npm: this.npm })
+    if (unreviewed.length > 0) {
+      const count = unreviewed.length
+      const noun = count === 1 ? 'package has' : 'packages have'
+      log.warn(
+        'rebuild',
+        `${count} ${noun} install scripts not yet covered by allowScripts. ` +
+        'Run `npm approve-scripts --allow-scripts-pending` to review.'
+      )
+    }
+
     output.standard('rebuilt dependencies successfully')
   }
 

lib/commands/update.js

@@ -1,6 +1,8 @@
 const path = require('node:path')
 const { log } = require('proc-log')
 const reifyFinish = require('../utils/reify-finish.js')
+const resolveAllowScripts = require('../utils/resolve-allow-scripts.js')
+const strictAllowScriptsPreflight = require('../utils/strict-allow-scripts-preflight.js')
 const ArboristWorkspaceCmd = require('../arborist-cmd.js')
 
 class Update extends ArboristWorkspaceCmd {
@@ -19,6 +21,9 @@ class Update extends ArboristWorkspaceCmd {
     'package-lock',
     'foreground-scripts',
     'ignore-scripts',
+    'allow-scripts',
+    'strict-allow-scripts',
+    'dangerously-allow-all-scripts',
     'audit',
     'before',
     'min-release-age',
@@ -51,15 +56,19 @@ class Update extends ArboristWorkspaceCmd {
     }
 
     const Arborist = require('@npmcli/arborist')
+    const { policy: allowScriptsPolicy } = await resolveAllowScripts(this.npm)
     const opts = {
       ...this.npm.flatOptions,
       path: where,
       save,
       workspaces: this.workspaceNames,
+      allowScripts: allowScriptsPolicy,
     }
     const arb = new Arborist(opts)
 
-    await arb.reify({ ...opts, update })
+    const reifyOpts = { ...opts, update }
+    await strictAllowScriptsPreflight({ arb, npm: this.npm, idealTreeOpts: reifyOpts })
+    await arb.reify(reifyOpts)
     await reifyFinish(this.npm, arb)
   }
 }