npm Stage-only Tokens: Der Bot lädt hoch, der Mensch veröffentlicht

npm ist Paketregister und Kommandozeilenwerkzeug für JavaScript- und TypeScript-Pakete. Die neue Tokenberechtigung Read and write (stage only) trennt zwei Schritte: Eine CI-Pipeline lädt eine Paketversion in einen Prüfzustand; ein Maintainer veröffentlicht sie erst nach Kontrolle und Zwei-Faktor-Authentifizierung, kurz 2FA.

So sieht der Ablauf aus

Vorausgesetzt werden ein bereits bestehendes Paket, Veröffentlichungsrecht, aktivierte 2FA, npm ab 11.15.0 und Node.js ab 22.14.0. Die Automatisierung verwendet statt npm publish:

npm stage publish

Die Version landet im Staging-Bereich, einem noch nicht öffentlich installierbaren Prüfzustand. Maintainer listen die Stages eines Pakets auf:

npm stage list @acme/example

Die Ausgabe enthält für jede vorbereitete Version eine Stage-ID. Genau diese ID — nicht @scope/paket@version — gehört in die Folgebefehle:

npm stage view <stage-id>
npm stage download <stage-id>
npm stage approve <stage-id>

view zeigt die Details; download lädt das vorbereitete Paketarchiv zur Prüfung. Erst approve veröffentlicht die Stage, und dafür verlangt npm 2FA. Ein Stage-only-Token darf diesen endgültigen Freigabeschritt nicht selbst ausführen.

Zwei Authentisierungswege, derselbe Prüfhalt

Staged Publishing ist mit zwei Automatisierungswegen kombinierbar:

• Stage-only-Token: ein langlebiger npm-Token mit der Berechtigung „Read and write (stage only)“ authentisiert npm stage publish.
• Trusted Publishing: OpenID Connect, kurz OIDC, authentisiert einen freigegebenen CI-Workflow mit kurzlebigen Nachweisen statt eines dauerhaft gespeicherten npm-Tokens. Auch dieser Workflow kann npm stage publish verwenden.

In beiden Fällen muss ein Maintainer die Stage anschließend prüfen und mit 2FA freigeben. OIDC reduziert das Risiko eines langlebigen Geheimnisses; Staging trennt Upload und Veröffentlichung. Es sind zwei Achsen, keine Alternativen.

Ein schematischer CI-Schritt mit Stage-only-Token sieht so aus:

- run: npm ci
- run: npm test
- run: npm stage publish
  env:
    NODE_AUTH_TOKEN: $

Das Beispiel setzt eine bereits eingerichtete, kompatible Node-/npm-Umgebung voraus. npm bestätigt mit dem Staging-Schritt weder Paketqualität noch Lieferkettenvertrauen; es fügt nur einen Freigabehalt ein.

Stage-only heißt nicht „nur diese eine Schreibaktion“

Der Token blockiert direkte Veröffentlichung und das Freigeben einer Stage. Er ist aber kein allgemeiner Leseschlüssel: Laut Ankündigung können seine übrigen Paket-Schreibrechte weiterhin das Verschieben von Dist-Tags oder das Deprecaten von Versionen erlauben. Teams müssen Paket- und Organisationsumfang deshalb weiterhin möglichst eng wählen.

Bestehende Tokens ändern sich durch die Neuerung nicht automatisch. npm zielt nach aktueller Planung darauf, direkte Veröffentlichungen mit Bypass-2FA-Tokens ab Januar 2027 nicht mehr zuzulassen. Das ist der angekündigte Zieltermin mit Quellenstand 20. September 2026, keine bereits vollzogene Abschaltung.

Eine vernünftige Umstellung

1. Prüfen, ob der CI-Anbieter Trusted Publishing unterstützt; wenn ja, OIDC statt eines langlebigen Tokens erwägen.
2. Staged Publishing unabhängig davon als menschlichen Freigabehalt einrichten.
3. Wenn OIDC nicht unterstützt wird, einen Stage-only-Token mit engem Paket- und Organisationsumfang verwenden.
4. npm publish durch npm stage publish ersetzen.
5. Stage-ID aus npm stage list übernehmen, Archiv prüfen und mit 2FA freigeben.
6. Alte, weiter reichende Publish-Tokens widerrufen, sobald kein Workflow sie mehr benötigt.

Die neue Funktion macht aus „hochgeladen“ und „öffentlich“ zwei getrennte Zustände. Genau diese kleine Tür ist ihr Sicherheitsgewinn.

Quellen

• GitHub Changelog: Stage-only npm tokens for safer automation, 18. September 2026
• npm Docs: Staged publishing, abgerufen am 20. September 2026
• npm Docs: Trusted publishers, abgerufen am 20. September 2026

Quellenstand: 20. September 2026.