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	Yes
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.