Kann ein npm Stage-only Token einem AI Agent direkt Pakete veröffentlichen? Abnahme 2026

Diese Abnahme richtet sich an Teams, die einen Coding-Agenten automatisch entwickeln, packen oder eine npm-Version vorbereiten lassen, aber die letzte Veröffentlichung nicht an denselben Prozess delegieren wollen. Sie ist ebenso für Plattformteams mit CI/CD und GitHub Actions gedacht wie für Teams, die native Abhängigkeiten oder plattformübergreifende Artefakte auf einem Remote Mac bauen.

Letzte Aktualisierung: 19.09.2026. Die Angaben wurden anhand des offiziellen GitHub-Änderungsprotokolls zum Stage-only-Token, der npm-Dokumentation zu staged publishing und der npm-Dokumentation zu Trusted Publishing geprüft.

1Die Sicherheitsgrenze zwischen Staging und Veröffentlichung

Der entscheidende Unterschied lautet: Ein Stage-only Token kann eine direkte Veröffentlichung blockieren, es macht den auslösenden AI-Agenten aber nicht automatisch zu einem reinen Vorbereitungswerkzeug. npm führt für diese Token-Klasse die Berechtigung „Read and write (stage only)“. Der Token darf damit eine Version in den vorgesehenen Prüfablauf übergeben, nicht aber ohne die erforderliche Bestätigung als öffentlich veröffentlichte Version freischalten. Diese Trennung ist der Kern von npm staged publishing und wird im npm-Leitfaden zum Staging-Verfahren beschrieben.

Für Ihre Abnahme müssen Sie daher fünf Vorgänge getrennt bewerten:

• Code erzeugen oder verändern;
• Tests und Build ausführen;
• das Paket beziehungsweise den Tarball erzeugen;
• eine Version zur Prüfung bereitstellen;
• die endgültige Veröffentlichung mit der persönlichen 2FA-Identität genehmigen.

Die ersten vier Schritte können in geeigneten Grenzen automatisiert werden. Der fünfte Schritt darf nicht nur deshalb beim Agenten landen, weil der direkte npm publish-Aufruf scheitert. Ein Agent kann weiterhin über Skripte, vorhandene Werkzeuge oder zusätzliche API-Aufrufe versuchen, andere Paketressourcen zu verändern. Die npm-Dokumentation zu Zugriffstoken und deren Berechtigungen ist deshalb für die Rechteprüfung wichtiger als die bloße Beobachtung eines einzelnen Fehlers.

Die geplante Entfernung der direkten Veröffentlichung mit bypass-2FA-Token ist für Januar 2027 vorgesehen. Das ist ein offizieller Planungstermin, keine unveränderliche Zusage. Ihre Entscheidung sollte deshalb nicht auf dem Kalenderdatum beruhen, sondern auf nachweisbaren Negativtests: Der Agent muss eine direkte Veröffentlichung nicht nur heute, sondern auch nach einer Änderung der CI-Konfiguration, eines Skripts oder eines Paket-Tags zuverlässig verweigern.

2Rollenaufteilung für Maintainer und AI-Coding-Teams

Maintainer: Inhalt vor Freigabe

Die Person, die das Paket betreut, prüft nicht nur, ob ein neuer Tarball erzeugt wurde. Sie vergleicht mindestens:

• die erwartete Versionsnummer mit dem Commit;
• die enthaltenen Dateien und die files- beziehungsweise Ignore-Regeln;
• die Herkunft aller generierten Artefakte;
• die Änderungen gegenüber der letzten freigegebenen Version;
• die Testergebnisse und den verwendeten Build-Aufruf;
• die Begründung, warum diese Version veröffentlicht werden soll.

Eine erfolgreiche Übergabe in die npm-Staging-Phase ist kein Beleg dafür, dass der Inhalt sicher oder korrekt ist. Ein Agent kann eine unerwartete Datei packen, eine Versionsnummer erhöhen, generierte Ausgaben aus einer nicht reproduzierbaren Umgebung übernehmen oder eine Abhängigkeit aktualisieren, die im Review nicht vorgesehen war.

Bewahren Sie deshalb für jede Übergabe eine Zuordnung zwischen Commit, Build-Lauf, erzeugtem Tarball, Testprotokoll und menschlicher Freigabe auf. Der Beleg muss auch nach dem Ende des Agentenlaufs lesbar sein; eine Chat-Antwort des Agents genügt nicht.

AI-Coding-Team: begrenzte Aktionen statt umfassender Paketverwaltung

Der Agent sollte nur die Aktionen ausführen können, die für die Vorbereitung erforderlich sind. Dazu gehören beispielsweise die Änderung im zugewiesenen Arbeitsbereich, die lokalen Tests, die Paketerzeugung und die Übergabe an den Staging-Prozess. Die Umgebung darf nicht zusätzlich über ein langlebiges persönliches Veröffentlichungsgeheimnis verfügen.

Besonders wichtig sind Skripte, die scheinbar nur „aufräumen“ oder Metadaten aktualisieren. Prüfen Sie, ob sie dist-tag-Beziehungen verschieben, eine Version zurückziehen, eine Warnung setzen oder Paketdaten außerhalb des Zielpakets verändern können. Ein Stage-only Token verhindert die direkte Veröffentlichung einer neuen Version; es ersetzt aber weder eine minimale Rechtevergabe noch eine erlaubte-Aktion-Liste.

Binden Sie jeden Lauf an einen eigenen Arbeitsbereich, einen nachvollziehbaren Commit und einen eindeutig identifizierbaren Staging-Vorgang. Wiederverwendete Arbeitsverzeichnisse sind riskant, wenn dort ein früherer Tarball, eine npm-Konfigurationsdatei oder ein fehlgeschlagener Agentenlauf zurückbleibt.

Plattformteam: Token oder OIDC

Für GitHub Actions und vergleichbare CI/CD-Systeme stehen zwei unterschiedliche Wege zur Diskussion.

Stage-only Token ist der pragmatische Übergang, wenn Ihr Ablauf noch eine manuelle Freigabe benötigt, der verwendete Runner nicht für Trusted Publishing unterstützt wird oder Sie den bestehenden Prozess zunächst mit einer engeren Veröffentlichungserlaubnis absichern wollen. Das Token muss auf das erforderliche Paket und den erforderlichen Zweck begrenzt werden. Ein dauerhaftes Token in einer globalen Runner-Umgebung ist keine ausreichende Umsetzung.

Trusted Publishing ist der bevorzugte Prüfpunkt, wenn Ihr CI/CD-Anbieter und Ihr Workflow die von npm unterstützte OIDC-Identität verwenden können. Dabei wird die Berechtigung an die Identität des Workflows gebunden, statt ein langlebiges Schreibgeheimnis als Standard in der Pipeline zu hinterlegen. Die aktuelle npm-Übersicht zu Trusted Publishing legt jedoch nicht fest, dass dadurch jede weitere Kontrolle entfällt. Sie müssen weiterhin Workflow, Repository, Paketberechtigung, Runner und Freigabeschritt zusammen prüfen.

Seit dem GitHub-Update zu mehreren Trusted-Publishing-Konfigurationen für npm lohnt sich eine erneute Prüfung, ob Ihr Paket mehrere zulässige Veröffentlichungswege benötigt. Mehrere Konfigurationen dürfen nicht zu einer unübersichtlichen Liste von Workflows führen, deren Herkunft niemand mehr eindeutig kontrolliert.

Ihre Entscheidung lässt sich so treffen:

• Stage-only beibehalten, wenn eine manuelle 2FA-Abnahme fest vorgeschrieben ist und OIDC für Ihren Ablauf noch nicht belastbar nachgewiesen wurde.
• Auf Trusted Publishing migrieren, wenn die Workflow-Identität, die Paketbindung und die Runner-Eigenschaften reproduzierbar geprüft wurden und kein langlebiger Schreib-Token erforderlich bleibt.
• Parallelbetrieb, wenn ein bestehender Produktionsweg weiterlaufen muss, aber ein neuer OIDC-Ablauf zunächst mit einem risikoarmen Paket getestet wird.
• Nicht freigeben, wenn weder Token-Isolation noch OIDC-Herkunft noch eine nachvollziehbare manuelle Abnahme nachweisbar sind.

3Sicherheitsabnahme für Restrechte und Geheimnisse

Die wichtigste Prüfung ist nicht „funktioniert npm publish?“, sondern „welche Aktionen funktionieren noch, obwohl npm publish abgewiesen wird?“. Führen Sie die Tests in einem isolierten Testpaket und mit einer absichtlich begrenzten Identität aus. Verwenden Sie kein produktives Paket, um Grenzfälle zu erforschen.

Prüfobjekte

Prüfen Sie zunächst die direkte Veröffentlichung einer neuen Version. Der Vorgang muss abgewiesen werden. Dokumentieren Sie Befehl, Zeitpunkt, Workflow-Lauf, Rückmeldung und verwendete Token-Klasse. Die offiziellen Anleitungen zum Erstellen und Anzeigen von npm-Token helfen dabei, die tatsächlich eingesetzte Tokenart zu verifizieren, statt nur den Namen einer Secret-Variable zu übernehmen.

Testen Sie danach getrennt:

• das Verschieben eines dist-tag;
• das Zurückziehen oder Kennzeichnen einer Version;
• Änderungen an Paketmetadaten;
• den Zugriff auf ein anderes Paket;
• die Nutzung des Tokens aus einem nicht vorgesehenen Repository oder Workflow;
• die Wiederverwendung nach Abschluss des Laufs.

Die Aufgabe ist nicht, möglichst viele schädliche Befehle auszuführen, sondern die genehmigte und die verbotene Aktionsfläche nachweisbar zu dokumentieren. Ein erfolgreicher Tag-Wechsel kann beispielsweise die Auslieferung einer bereits vorhandenen Version beeinflussen, obwohl keine neue Version veröffentlicht wurde.

Geheimnisgrenzen

Suchen Sie Tokenwerte in vier Bereichen: CI-Logs, Caches, Arbeitsbereichssnapshots und Agenten- beziehungsweise Unteragenten-Kontexte. Maskierung im Log reicht nicht, wenn ein Build-Skript den Wert in eine Datei schreibt oder ein Snapshot das komplette Arbeitsverzeichnis archiviert.

Legen Sie außerdem fest, wer ein Token widerrufen darf, wie die Rotation ausgelöst wird und welcher Nachweis nach einem Widerruf gespeichert wird. Für DSGVO-relevante Umgebungen ist zusätzlich zu dokumentieren, welche Build-Logs personenbezogene oder interne Repository-Informationen enthalten und wie lange sie aufbewahrt werden.

4Remote-Mac-Builds und getrennte Freigabeidentitäten

Ein Remote Mac ist bei nativen Abhängigkeiten, macOS-spezifischen Testläufen oder plattformübergreifenden Binärdateien ein Build-Ort, keine automatische Freigabestation. Der Rechner darf den Quellcode auschecken, Abhängigkeiten installieren, Tests ausführen und einen nachvollziehbaren Tarball erzeugen. Die persönliche 2FA-Identität des Maintainers gehört nicht in dieselbe Umgebung.

Die Trennung ist besonders wichtig, wenn ein AI-Agent den Build steuert. Der Agent benötigt eventuell Zugriff auf Compiler, Signaturwerkzeuge oder Testdienste, aber daraus darf kein allgemeiner Zugang zum npm-Konto entstehen. Bewahren Sie die Freigabe außerhalb des Build-Hosts auf und übertragen Sie zur Prüfung nur die notwendigen Nachweise: Commit, Tarball-Prüfsumme, Testprotokoll, Paketinhalt und Staging-Referenz.

Wenn Sie einen Remote-Mac-Ablauf einführen, gehen Sie in dieser Reihenfolge vor:

1. Erstellen Sie einen kurzlebigen Arbeitsbereich ohne Altlasten aus früheren Builds.
2. Prüfen Sie, welcher Commit ausgecheckt wurde, und speichern Sie diese Zuordnung im Build-Protokoll.
3. Übergeben Sie nur das Stage-only Token mit der kleinstmöglichen Reichweite; legen Sie keine persönliche 2FA-Identität ab.
4. Führen Sie Tests, Paketerzeugung und Inhaltsprüfung aus, ohne Geheimnisse in Ausgaben oder Artefaktdateien zu schreiben.
5. Übergeben Sie Tarball, Prüfsumme, Testergebnisse und Änderungsnachweis zur unabhängigen Prüfung.
6. Löschen Sie Token, npm-Konfiguration, Caches und Arbeitsbereich nach Abschluss oder Fehlschlag.
7. Prüfen Sie den Wiederherstellungsfall: Der Token muss widerrufbar sein, und der nächste Lauf darf nicht von einem alten Arbeitsverzeichnis abhängen.

Wenn Sie für native npm-Abhängigkeiten eine getrennte Mac-Ausführungsumgebung benötigen, prüfen Sie die deutschsprachige Dokumentation zur Remote-Mac-Nutzung und die Hinweise zu geeigneten Build-Abläufen. Diese Informationen ersetzen jedoch nicht Ihre eigene Abnahme von Token, Arbeitsbereich, Logs und Wiederherstellung; sie dienen lediglich dazu, die Umgebung getrennt vom npm-Freigabekonto zu planen.

5Die Abnahme als ausführbare Checkliste

Verwenden Sie die folgende Liste nicht als allgemeine Absichtserklärung, sondern speichern Sie zu jedem Punkt den konkreten Lauf, die verantwortliche Person und den zugehörigen Nachweis:

• [ ] Der Stage-only Token wurde eindeutig identifiziert und ist nicht mit einem persönlichen Vollzugriffstoken vermischt.
• [ ] Ein direkter Versuch, eine neue Version mit npm publish zu veröffentlichen, wurde mit diesem Token ausgeführt und nachweisbar abgewiesen.
• [ ] Der Agent kann nur den vorgesehenen Arbeitsbereich ändern und erhält keinen Zugriff auf die persönliche 2FA-Identität.
• [ ] Commit, Build-Lauf, Tarball, Testprotokoll und Staging-Referenz sind einander eindeutig zugeordnet.
• [ ] dist-tag-Änderungen wurden als eigener Negativtest geprüft und entweder verhindert oder ausdrücklich freigegeben.
• [ ] Rücknahme, Kennzeichnung und sonstige Paketmetadatenänderungen wurden separat getestet.
• [ ] Der Zugriff auf ein nicht vorgesehenes Paket und ein nicht vorgesehenes Repository wurde geprüft.
• [ ] Tokenwerte erscheinen weder in CI-Logs noch in Caches, Snapshots, Artefaktdateien oder Agenten-Kontexten.
• [ ] Der Remote Mac enthält keine dauerhaft gespeicherte 2FA-Identität und wird nach dem Lauf von Token und Arbeitsbereich bereinigt.
• [ ] Für Trusted Publishing sind Workflow-Identität, Repository, Paket, Runner und Freigaberegel dokumentiert.
• [ ] Eine verantwortliche Person kann die finale 2FA-Freigabe oder die bewusste Ablehnung nachvollziehbar zuordnen.
• [ ] Widerruf, Rotation und Wiederanlauf nach einem fehlgeschlagenen Build wurden praktisch geprüft.

Besteht einer der ersten vier Punkte nicht, sollte der Agent keine produktive Staging-Übergabe erhalten. Fehlen nur Nachweise zu Restrechten oder Bereinigung, bleibt der Prozess auf ein Testpaket begrenzt. Eine vollständige Freigabe ist erst vertretbar, wenn die direkte Veröffentlichung blockiert, der Staging-Inhalt prüfbar, die 2FA-Abnahme verantwortlich und der Fehlerfall widerrufbar ist.

6Zeitplan und Entscheidung je Verantwortungsgruppe

In dieser Woche: Basistest

Der Maintainer erstellt ein risikoarmes Testpaket. Das AI-Coding-Team führt den vollständigen Vorbereitungsprozess aus. Das Plattformteam zeichnet Identität, Runner, Repository und Paketbindung auf. Die Sicherheitsverantwortlichen prüfen direkte Veröffentlichung, Restrechte und Geheimnisspuren.

Der Basistest ist nur bestanden, wenn der direkte Veröffentlichungsversuch abgewiesen wird, der Staging-Tarball unabhängig geprüft werden kann und kein Token in Logs, Caches oder Snapshots verbleibt.

Vor der ersten produktiven Nutzung: Vier Beleggruppen

Speichern Sie mindestens diese vier Beleggruppen:

• Veröffentlichung verweigert: Der direkte npm publish-Versuch mit Stage-only Token wurde abgewiesen.
• Staging prüfbar: Tarball, Commit, Tests und Paketinhalt sind einander zugeordnet.
• 2FA verantwortlich: Die endgültige Freigabe wurde von einer identifizierten Person außerhalb des Agentenlaufs erteilt.
• Fehler widerrufbar: Token, Workflow und Artefakte können nach einem Fehler gesperrt, gelöscht oder zurückgezogen werden.

Hochrisikopakete und Ausnahmen

Bei einem wenig kritischen Paket kann „Agent bereitet vor, Maintainer genehmigt“ ein vertretbarer Start sein. Bei Paketen mit hoher Verbreitung, sicherheitsrelevanter Funktion oder vielen abhängigen Projekten sollte zusätzlich eine unabhängige Wiederholung des Builds und eine zweite Freigabeperson eingeplant werden.

Kann Ihr Team die Herkunft des Tarballs nicht rekonstruieren, dürfen Sie den Prozess nicht durch ein stärkeres Token „reparieren“. Fehlt die Isolation des Remote Mac, sollte der Build zunächst in einer neu aufgebauten Umgebung erfolgen. Fehlt die OIDC-Nachvollziehbarkeit, bleibt ein begrenztes Stage-only Token mit manueller 2FA-Abnahme besser als ein unkontrolliertes langlebiges Schreib-Token.

7FAQ zur Abnahme

Stage-only Token und direkte Veröffentlichung

Ja, die direkte Veröffentlichung einer neuen Version wird blockiert. Die Blockade ist aber enger als eine vollständige Paketverwaltungssperre. Prüfen Sie deshalb zusätzlich Tag-Verschiebungen, Versionsrücknahmen, Metadatenänderungen und Zugriffe auf fremde Pakete. Erst wenn diese Aktionen dokumentiert oder abgewiesen sind, kennen Sie die tatsächliche Grenze des Agents.

Staged Publishing oder Trusted Publishing

Wählen Sie staged publishing, wenn die menschliche Prüfung ein fester Bestandteil Ihres Freigabeprozesses ist oder OIDC noch nicht sicher unterstützt wird. Trusted Publishing ist für geeignete CI/CD-Workflows attraktiver, weil langlebige Schreib-Token entfallen können. Die OIDC-Variante macht den Workflow jedoch nicht automatisch vertrauenswürdig; Repository, Paket und Runner benötigen weiterhin eine klare Zuordnung.

Manuelle 2FA beim AI-Coding-Agenten

Der Agent kann den Code ändern, Tests ausführen, ein Paket bauen und die Staging-Übergabe vorbereiten. Die finale Veröffentlichung sollte beim Maintainer mit 2FA bleiben, weil dort Version, Inhalt, Herkunft und Änderungsumfang geprüft werden. Eine fehlgeschlagene automatische Veröffentlichung ist kein Ersatz für diese Prüfung und beweist nicht, dass der erzeugte Inhalt korrekt ist.

Token auf dem Remote Mac

Das Token sollte nur für den notwendigen Lauf verfügbar sein und nicht in einem dauerhaften Benutzerprofil, einem Cache oder einem Arbeitsbereichsabbild verbleiben. Entfernen Sie es nach Erfolg und Fehlschlag. Die persönliche 2FA-Identität bleibt außerhalb des Build-Hosts. Für native Artefakte müssen Sie zusätzlich beweisen, dass Quellcommit, Build, Signatur und Staging-Tarball zusammengehören.

Verbleibende npm-Schreibrechte

Stage-only beschränkt die Veröffentlichung einer neuen Version, nicht zwingend alle Paketaktionen. Die offiziellen Hinweise nennen weiterhin mögliche Schreibvorgänge wie die Verwaltung von dist-tags oder das Zurückziehen beziehungsweise Kennzeichnen von Versionen. Behandeln Sie diese Rechte als eigene Angriffsfläche und testen Sie sie mit einer kontrollierten Paketidentität.

8Entscheidung für Ihren nächsten Release-Zyklus

Für einen kleinen, risikoarmen Release ist ein begrenzter AI-Agent mit Stage-only Token, isoliertem Arbeitsbereich und manueller 2FA-Abnahme ein vertretbarer Pilot. Für produktionskritische Pakete sollten Sie zusätzlich unabhängige Tests, eine zweite Freigabeperson und eine reproduzierbare Artefaktprüfung verlangen. Unterstützt Ihr CI/CD-System eine belastbare OIDC-Identität, prüfen Sie Trusted Publishing parallel, statt ein langlebiges Schreib-Token dauerhaft zu erweitern.

Ein unkontrollierter Agent mit vollständiger Paketverwaltung bleibt dagegen die falsche Abkürzung. Auch ein lokaler Mac oder ein Remote Mac löst das Problem nicht, wenn Build, Token und Freigabeidentität im selben Arbeitsbereich liegen. Wenn Sie für einzelne Builds, native Abhängigkeiten oder zeitlich begrenzte CI/CD-Tests eine separate Ausführungsumgebung benötigen, planen Sie diese als isolierten Build-Ort und nicht als Ablage für die persönliche 2FA-Identität. Das verbessert die Nachvollziehbarkeit, beseitigt aber nicht automatisch die npm-Risiken.

Bevor Sie den ersten produktiven Agentenlauf freigeben, sollten Sie daher die Umgebung, den Stage-only Token und die menschliche Genehmigung strikt auseinanderhalten und anschließend nur einen klar begrenzten Release-Pfad aktivieren. Entscheidend ist nicht, ob der Agent „veröffentlichen kann“, sondern ob Sie jeden vorbereiteten Tarball zurückverfolgen, jede Restberechtigung erklären und jede finale Freigabe einer verantwortlichen Person zuordnen können.