feat: npm stage

[reggi]

Introducing npm stage 🎉

A new command for staged publishing — allowing package maintainers to decouple the act of publishing from proof-of-presence (2FA), making automated workflows more secure.

🔗 Docs

Why Staged Publishing?

With npm stage publish, an automated workflow can stage a package version without a 2FA prompt. The maintainer can then review and approve the staged package at their convenience, providing 2FA only at the approval step. This keeps proof-of-presence in the loop while keeping CI/CD fully automated.

Subcommands

Command	Description	Requires 2FA
npm stage publish [<package-spec>]	Stage a package for publishing	No
npm stage list [<package-spec>]	List all staged package versions	No
npm stage view <stage-id>	View details of a specific staged package	No
npm stage approve <stage-id>	Approve and publish a staged package	Yes
npm stage reject <stage-id>	Reject and remove a staged package	Yes
npm stage download <stage-id>	Download the staged tarball for inspection	No

How It Works

1. Stage — CI runs npm stage publish using any token type (no 2FA needed). The package version is held in a pending state, not publicly available.
2. Review — Maintainer runs npm stage list to see pending staged packages, and npm stage view <id> or npm stage download <id> to inspect them.
3. Approve or Reject — Maintainer runs npm stage approve <id> (with 2FA) to publish, or npm stage reject <id> to discard.

Key Behaviors

• Staged packages share the same semver uniqueness constraint as published packages — you can't publish a version that's already staged.
• Normal npm publish continues to work alongside staged publishing.
• Multiple versions of the same package can be staged concurrently.
• npm stage publish has full parity with npm publish (respects "private": true, workspace support, etc).
• Tags are immutable once staged — reject and re-stage to change a tag.

Future Work

• Trust relationship permissions — A follow-up PR will add granular command permissions to npm trust, with --allow-publish and --allow-stage-publish flags to control whether a trust relationship can be used for npm publish, npm stage publish, or both.

[ljharb]

Why would download not require 2fa but view require it? Either both should, or neither, I’d expect.

[reggi]

Why would download not require 2fa but view require it? Either both should, or neither, I’d expect.

@ljharb that was a mistake, fixed!

[ljharb]

(i'm assuming that all the "no"s still require one factor)

[wraithgar]

(i'm assuming that all the "no"s still require one factor)

All staged content routes will require authentication with access to that package.

[reggi]

Regarding the redact: false change in display.js:

The JSON output buffer now redacts each item individually by default. Callsites can opt out of redaction by passing { redact: false } in the buffer meta. This was needed because @npmcli/redact redacts all UUIDs (including stageId), and there is no way to selectively redact parts of a merged JSON object after the fact.

We could not simply add stageId as a separate buffer entry because getArrayOrObject uses Object.assign to merge items — a second { [pkgName]: { stageId } } would overwrite the first { [pkgName]: { ...tarball } }. So the approach is: put stageId on the tarball contents and mark that entire buffer item as redact: false via logTar. The tarball metadata (name, version, shasum, etc.) does not contain sensitive data, so skipping redaction there is safe.

Note: publish --json already outputs multiple JSON objects in the webauthn flow, so a separate JSON output for stageId was also considered as an alternative simpler approach, but per-item buffer redaction is more correct long-term.

[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/9201 origin/release/v11
git cherry-pick -x 254809e318ee0046092d07d68a99154c3f672147
# resolve any conflicts, then:
git push origin backport/v11/9201

Error details

Command failed: git cherry-pick -x 254809e318ee0046092d07d68a99154c3f672147
error: could not apply 254809e31... feat: npm stage (#9201)
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"