npm sans jeton permanent : la provenance ne prouve pas qu’un paquet est sûr

Pour publier un paquet npm depuis GitHub Actions sans jeton d’écriture permanent, enregistrez le dépôt et le workflow comme Trusted Publisher, puis donnez au job la permission OIDC. La documentation npm sur Trusted Publishing décrit l’échange de cette identité contre des identifiants de courte durée et la possibilité de limiter le workflow à la publication par étape.

Après publication, un paquet public issu d’un dépôt public compatible peut recevoir automatiquement une attestation de provenance. Elle relie la version au code source et aux instructions de build déclarés. Elle ne détermine pas si le code est sûr : l’identité du workflow, l’intégrité du paquet téléchargé et l’innocuité de son contenu répondent à des questions différentes.

Associer le paquet au bon workflow

Dans les paramètres du paquet sur npmjs.com, ajoutez un Trusted Publisher de type GitHub Actions. Indiquez le propriétaire du dépôt, son nom et uniquement le nom du fichier de workflow, extension comprise, tel qu’il figure dans .github/workflows/. Si le job utilise un environnement GitHub, renseignez aussi son nom. L’identité présentée par le job devra correspondre exactement à ces valeurs ; vérifiez également que repository.url dans package.json désigne le dépôt utilisé pour publier.

Pour soumettre chaque version à un mainteneur avant sa diffusion, laissez la connexion autorisée à exécuter npm stage publish et désactivez son droit d’exécuter npm publish. L’autorisation npm dist-tag est distincte : accordez-la seulement si cette même connexion doit gérer les étiquettes de distribution. Examinez les autres connexions du paquet, car une connexion conservant le droit de publier directement reste une autre voie de sortie.

Le job doit tourner sur un runner hébergé par GitHub ; les runners autohébergés ne sont pas pris en charge. Trusted Publishing fonctionne aussi avec les environnements hébergés de GitLab CI/CD et de CircleCI, mais le réglage d’identité et les instructions qui suivent concernent GitHub Actions.

Créer le job de publication sans secret npm

Un workflow minimal peut tenir dans un seul job de sortie, déclenché par les tags de version que l’équipe contrôle. Le point décisif est la permission id-token: write : elle permet à GitHub Actions de présenter son identité OIDC. Ajoutez contents: read pour récupérer le dépôt et runs-on: ubuntu-latest pour utiliser un runner hébergé ; si un environnement a été enregistré dans npm, attachez ce même environment au job.

1. Créez .github/workflows/publish.yml, puis configurez le déclencheur sur les tags voulus, par exemple avec on.push.tags visant v*. Le nom publish.yml doit être celui enregistré pour le paquet.
2. Utilisez actions/checkout@v7, puis actions/setup-node@v7 avec node-version: '24', registry-url: 'https://registry.npmjs.org' et package-manager-cache: false. Le guide de setup-node fixe npm 11.5.1 comme version minimale pour Trusted Publishing et recommande de désactiver le cache dans un job de publication.
3. Exécutez npm ci, le build nécessaire et les tests du paquet. Terminez par npm stage publish, sans NODE_AUTH_TOKEN ni autre secret npm dans cette étape.

La désactivation du cache réduit le risque de réutiliser des dépendances mises en cache et altérées pendant une exécution qui possède une identité de publication. Si npm ci télécharge des dépendances privées, réservez un jeton limité à la lecture à cette seule étape. Le job de publication doit ensuite utiliser OIDC ; un jeton de lecture destiné à l’installation ne lui donne pas le droit de publier.

En cas d’échec d’authentification, comparez le propriétaire, le dépôt, le nom du fichier et l’éventuel environnement avec la configuration npm. Vérifiez ensuite la permission id-token: write, la version effective de npm et repository.url. Une connexion enregistrée sur npmjs.com ne valide pas à elle seule que le workflow pourra s’authentifier.

Faire approuver la version préparée

npm stage publish dépose la version sans la rendre immédiatement accessible au public. Un mainteneur peut examiner la version préparée, puis l’approuver ou la rejeter depuis npmjs.com ou la CLI avec une authentification interactive. Cette publication différée avec approbation ajoute une décision humaine entre l’exécution du workflow et la diffusion du paquet.

Dans la CLI, npm stage list retrouve les versions en attente, npm stage view affiche les détails d’une entrée et npm stage approve demande son identifiant. Ces commandes d’examen et d’approbation ne s’authentifient pas avec l’identité OIDC du job ; l’approbation requiert la double authentification du mainteneur. Il faut donc désigner la personne qui contrôle l’artefact préparé et celle qui peut autoriser sa sortie. Si une diffusion immédiate est voulue, la connexion doit recevoir séparément le droit npm publish et le job doit employer cette commande : la version n’attendra alors pas cette approbation.

Migrer avant de révoquer les anciens jetons

Préparez la connexion Trusted Publisher et le nouveau workflow pendant que l’ancien chemin de publication fonctionne encore. Planifiez la première exécution sur une version réelle : elle permet de constater que le job obtient son identité OIDC, prépare la version et que le mainteneur peut l’approuver. Créer la connexion sans effectuer ce parcours laisse une erreur de correspondance possible jusqu’au moment de la sortie.

Une fois cette publication réussie, choisissez dans les paramètres du paquet l’option qui impose la double authentification et interdit les jetons pour la publication traditionnelle. Révoquez les anciens jetons d’automatisation devenus inutiles, puis supprimez les secrets correspondants du dépôt. Cette restriction laisse fonctionner les connexions OIDC ; elle évite qu’un ancien jeton d’écriture conserve une voie de publication parallèle.

Si plusieurs workflows publient le même paquet, migrez-les un par un et contrôlez les droits de chaque connexion avant de supprimer l’ancien mécanisme. Une connexion limitée à npm stage publish ne restreint pas une autre connexion qui autorise encore npm publish. La restriction des jetons concerne l’authentification par jeton traditionnelle ; elle ne retire pas les droits de publication interactive des mainteneurs autorisés.

Vérifier la provenance sans lui attribuer une garantie de sûreté

La documentation npm sur la provenance décrit un lien vérifiable avec le code source et les instructions de build, ainsi que la vérification des attestations par npm audit signatures ; elle précise qu’une provenance établie ne garantit pas l’absence de code malveillant. Une attestation situe donc le parcours de fabrication du paquet, sans porter de jugement sur ce que ce parcours a produit.

Après l’approbation et la publication, installez la version concernée dans un projet de contrôle, puis lancez npm audit signatures avec une CLI npm récente. La commande vérifie les signatures du registre et les attestations disponibles pour les dépendances téléchargées. Son résultat porte sur l’ensemble installé : si plusieurs paquets y figurent, un total d’attestations vérifiées ne suffit pas à identifier la version qui vous intéresse. Consultez ses informations de provenance dans le registre pour retrouver le dépôt, le commit et le workflow associés.

Les signatures du registre aident à contrôler l’intégrité du paquet distribué ; l’attestation relie sa fabrication à une source et à un environnement déclarés. Du code malveillant peut néanmoins se trouver dans le dépôt ou être introduit par une étape de build autorisée. La génération automatique de provenance exige par ailleurs un paquet public publié depuis un dépôt public compatible avec GitHub Actions ou GitLab CI/CD sur un runner hébergé. Un dépôt privé ne remplit pas cette condition, et la publication OIDC depuis CircleCI ne bénéficie pas de cette génération automatique.

À lire aussi :

• npm accepte dix éditeurs OIDC, avec validation humaine après le scan
• npm ajoute un jeton qui prépare la publication sans pouvoir la déclencher
• Navana.ai lève 40 crores ₹ : douze langues ne garantissent pas la précision