Publier des paquets avec un agent IA sans multiplier les jetons de publication

Un agent de programmation IA doit pouvoir installer des dépendances sans avoir le pouvoir de publier, de retirer, de supprimer ou de retaguer des paquets. Ces opérations semblent proches dans une ligne de commande, mais leurs conséquences sont très différentes. Les traiter comme une seule permission transforme une tâche de développement courante en autorité de publication.

J'ai vu des identifiants de publication se multiplier parce qu'une équipe voulait qu'un agent exécute une simple commande d'installation sans danger. Le jeton restait ensuite dans l'environnement shell, un fichier de configuration ou la sortie d'une commande, où n'importe quel outil de cette exécution pouvait le réutiliser. L'incident qui suit ne commence que rarement par une compromission spectaculaire. Il commence par un agent qui exécute npm publish sur le mauvais registre, déplace latest avant que quiconque ait inspecté le tarball, ou tente un retrait parce qu'il a interprété trop littéralement une demande de nettoyage de test.

La lecture d'un registre ne donne pas l'autorité de publier

L'installation et la publication de paquets utilisent la même famille de points de terminaison de registre, mais elles répondent à des questions de confiance différentes. Un téléchargement demande : « Ce processus peut-il récupérer un artefact ? » Une publication demande : « Ce processus peut-il créer une version publique ou visible par l'organisation sous ce nom ? » Une suppression ou un retrait demande : « Ce processus peut-il modifier l'historique et la disponibilité d'une version que d'autres builds consomment peut-être déjà ? »

Ne regroupez pas ces questions dans un seul identifiant simplement parce que le client du registre les présente de façon similaire. Un gestionnaire de paquets peut lire sa configuration dans le même fichier .npmrc pour npm ci, npm publish, npm dist-tag add et npm unpublish. Cette organisation de fichier facilite la tâche du client, mais ne constitue pas une conception des permissions.

Pour un agent, séparez au moins les groupes d'actions suivants :

• Lecture : recherche de métadonnées, téléchargement du tarball, vérification de l'intégrité et installation des dépendances.
• Publication : création d'une nouvelle version immuable sous un nom de paquet approuvé.
• Routage : modification de canaux mutables comme latest, des tags de préversion ou des paramètres d'accès au registre.
• Destruction : retrait d'une publication, suppression d'un paquet lorsque le registre l'autorise et suppression d'un tag de publication.

La distinction entre publication et routage compte davantage que ne le laissent penser de nombreux scripts de publication. Une version peut être correcte, tandis que lui attribuer latest y dirige les nouveaux utilisateurs. À l'inverse, une préversion publiée sous un tag dédié peut présenter peu de risques si les utilisateurs doivent choisir ce tag. Les octets du paquet et le chemin que les utilisateurs empruntent pour y accéder sont deux contrôles distincts.

La suppression mérite sa propre catégorie, même lorsqu'un registre la limite. Les règles varient d'un registre à l'autre, et certaines opérations appelées « suppression » masquent seulement un artefact ou le rendent indisponible. Cela ne rend pas l'action inoffensive. Elle peut interrompre les installations reproductibles, les investigations d'incident et les équipes qui avaient verrouillé la version supprimée. Un agent ne doit jamais déduire qu'un nettoyage est sans danger simplement parce que la version a été publiée quelques minutes plus tôt.

Les jetons de publication trop larges échouent de manière ordinaire

Un jeton de registre présent dans l'environnement d'un agent est une autorisation dans un format de fichier pratique. Ce n'est pas une instruction limitée. Si l'agent peut lire l'environnement ou un fichier de configuration, une injection de prompt dans une dépendance, un modèle de ticket, un journal de build ou un texte de terminal copié peut offrir un chemin vers l'identifiant.

La recommandation habituelle consiste à utiliser le périmètre le plus restreint proposé par le registre. C'est un bon conseil, mais il ne suffit pas. Un jeton limité à la publication peut tout de même publier une version indésirable, dans un paquet inattendu auquel son compte a accès, ou vers un point de terminaison choisi par une configuration modifiée. La restriction réduit l'ampleur des dégâts. Elle ne détermine pas l'intention de chaque publication.

J'ai dû réparer plusieurs fois un incident qui suivait ce schéma :

1. Une équipe donne à un agent un jeton de registre pour qu'il puisse exécuter des contrôles de publication.
2. La configuration du projet pointe vers le registre de production, car c'est celui utilisé sur les postes des développeurs.
3. L'agent doit vérifier le contenu du paquet et exécute npm pack, ce qui est sans danger.
4. Une instruction ultérieure lui demande de « tester la publication » et l'agent exécute npm publish au lieu de publier vers une destination isolée.
5. La commande réussit, car le jeton et le nom du paquet sont valides. L'équipe ne s'en aperçoit qu'après que l'automatisation ou les utilisateurs ont vu la nouvelle version.

Aucun acteur malveillant n'est nécessaire dans cette chaîne. La conception a donné à un système de planification un identifiant et lui a demandé de préserver une limite que l'environnement d'exécution n'imposait pas.

Gardez l'identifiant en dehors du processus de l'agent. Confiez-le à une passerelle d'actions distincte, qui exécutera une requête HTTP ou une commande précise après avoir vérifié la destination demandée et obtenu l'approbation humaine requise. Sallyport suit ce modèle : l'agent reçoit le résultat d'une action autorisée, jamais le jeton du registre lui-même.

Cette conception exige tout de même des définitions d'actions précises. Une passerelle qui approuve « toute requête vers registry.example » n'a fait que déplacer le problème du jeton trop large derrière un bouton. La requête doit présenter suffisamment de détails pour que l'approbateur distingue la récupération d'un tarball de la publication d'une version, et la publication d'un paquet de son retrait.

Rendez la demande de publication vérifiable avant son exécution

Une personne ne peut pas approuver une instruction vague comme « publie le paquet ». La demande d'approbation doit afficher l'identifiant du paquet, la version exacte, l'hôte du registre, l'opération et la modification de tag éventuelle. Si l'agent ne peut pas fournir ces informations, il n'a pas encore préparé une demande de publication.

Pour un registre compatible avec npm, séparez le travail en une phase d'inspection de l'artefact et une phase de modification du registre. La phase d'inspection peut s'exécuter sans autorité de publication :

npm ci
npm test
npm pack --json

npm pack --json renvoie des informations structurées sur le tarball qu'il créerait. Les éléments utiles ont une forme similaire à celle-ci :

[
  {
    "id": "@acme/[email protected]",
    "name": "@acme/widget",
    "version": "1.4.0",
    "filename": "acme-widget-1.4.0.tgz",
    "files": [
      {"path": "README.md", "size": 2400},
      {"path": "dist/index.js", "size": 18420},
      {"path": "package.json", "size": 910}
    ]
  }
]

Inspectez la liste des fichiers, pas seulement le code de sortie de la commande. Je cherche les répertoires de sources qui auraient dû rester privés, les fichiers de test contenant des identifiants, un répertoire de sortie compilé manquant et des métadonnées de paquet qui indiquent le mauvais point d'entrée. npm pack est l'étape où ces erreurs restent faciles à corriger.

Récupérez ensuite séparément l'état du registre. La documentation de la CLI npm décrit npm view comme un moyen d'inspecter les métadonnées d'un paquet dans le registre. Utilisez-le pour poser des questions précises plutôt que d'accepter un vaste ensemble de données :

npm view @acme/widget version dist-tags --json
npm view @acme/[email protected] dist --json

La première commande vous indique quelle version existe et vers quoi pointent les tags. La seconde est utile après la publication, car dist contient l'adresse du tarball enregistrée par le registre ainsi que les données d'intégrité. Un workflow de publication doit conserver cette sortie dans son dossier de publication, après suppression des secrets, car elle décrit ce que le registre a accepté plutôt que ce que le répertoire local prévoyait d'envoyer.

Construisez la demande d'approbation à partir de ces faits. Une bonne demande dit : publier @acme/[email protected] vers registry.example, sans déplacer de tag. Une mauvaise demande dit : exécuter npm publish. La première permet à la personne chargée de l'examen de repérer une erreur d'espace de noms. La seconde lui demande de reconstituer l'intention à partir d'une commande qui n'est peut-être pas fiable.

Un paquet temporaire prouve le fonctionnement du chemin du registre

Un paquet temporaire est le moyen le plus sûr de tester le chemin qui transforme un tarball préparé en version récupérable dans un registre. Il ne prouve pas que votre paquet de production est prêt. Il prouve que l'authentification, le choix du registre, les mécanismes de publication et l'installation propre fonctionnent ensemble avec des contrôles proches de ceux de la vraie publication.

Utilisez un nom de paquet sous un espace de noms que vous contrôlez et rendez clairement temporaire. N'imitez pas le nom d'un paquet populaire et n'utilisez pas un nom qui pourrait devenir accidentellement un vrai produit. Ajoutez-y un tout petit module inoffensif. Son rôle est d'être publié et installé, pas de démontrer le comportement d'une application.

Ce package.json minimal rend le test facile à comprendre :

{
  "name": "@acme-release-test/relay-check-2025-04",
  "version": "0.0.1",
  "description": "Temporary registry release-path check",
  "main": "index.js",
  "files": ["index.js", "README.md"],
  "publishConfig": {
    "access": "restricted"
  }
}

Choisissez des paramètres d'accès qui correspondent au type réel de votre paquet. Ne copiez pas restricted sans réfléchir si votre vrai paquet est public, et ne rendez pas un test temporaire public simplement parce que cela semble plus réaliste. Le but est de tester la même limite d'autorisation et de public visé. Si la publication publique est le comportement à tester, utilisez un nom public explicitement temporaire et vérifiez les règles de conservation et de retrait du registre avant de commencer.

Exécutez le test dans un répertoire vierge afin que les métadonnées mises en cache et un espace de travail existant ne donnent pas une image trop favorable du résultat :

mkdir release-path-check
cd release-path-check
npm init -y
npm install @acme-release-test/[email protected]
node -e "console.log(require('@acme-release-test/relay-check-2025-04'))"

Une commande npm install réussie répond à une question plus utile qu'une réponse de publication réussie : un consommateur vierge peut-il résoudre et récupérer la version indiquée ? Si votre paquet utilise des exports, des déclarations de types, un exécutable en ligne de commande ou un script postinstall, testez aussi le point d'entrée public concerné dans ce répertoire vierge. Le fait que le registre ait stocké le paquet ne signifie pas que le consommateur peut l'utiliser.

Ne supprimez pas le paquet de test simplement pour garder un compte bien rangé. Conservez une trace d'audit conforme aux règles habituelles du registre, ou utilisez la dépréciation lorsque c'est approprié. Un test de publication doit apprendre à l'agent et à l'équipe à quoi ressemble un véritable enregistrement après publication. L'effacer leur apprend que l'historique des publications est négligeable.

Le contenu du paquet et l'acceptation par le registre sont deux tests distincts

Les équipes qualifient souvent npm pack de test de publication. C'est un test du contenu du paquet. Elles qualifient ensuite une commande npm publish réussie de test de publication. C'est un test d'acceptation par le registre. Aucun des deux ne remplace l'autre, et considérer l'un ou l'autre comme suffisant crée des lacunes prévisibles.

Le test du contenu du paquet vérifie que le tarball contient les fichiers et métadonnées prévus. Il détecte un accident de .npmignore, un tableau files trop large, un artefact compilé manquant et une différence de version entre les sources et le manifeste. Une grande partie de ce travail peut être effectuée sans accès réseau.

Le test d'acceptation par le registre vérifie que le registre reconnaît l'identifiant et l'espace de noms, accepte la version, stocke le tarball, enregistre les informations d'intégrité et le rend disponible pour un consommateur. Il détecte un mauvais hôte de registre, une habilitation d'organisation manquante, une erreur de configuration de publication et un chemin d'autorisation différent de celui du développement local.

Le test côté consommateur pose une troisième question : un projet vierge peut-il installer la version exacte et l'utiliser comme le feront les utilisateurs ? C'est là que se manifestent les dépendances entre pairs manquantes, les entrées exports incorrectes et la dépendance accidentelle à des fichiers de l'espace de travail.

Conservez ces tests dans cet ordre. Publier d'abord parce que « nous pourrons toujours retirer la version » est une mauvaise discipline. Le retrait n'est pas un bouton d'annulation. Certains utilisateurs, miroirs, caches et enregistrements de build peuvent conserver le paquet, tandis que d'autres consommateurs perdent la possibilité de le résoudre. Une version erronée peut être récupérable sur le plan opérationnel, mais elle crée tout de même du travail et de la confusion qu'une inspection locale du tarball aurait évités.

L'approbation doit correspondre aux conséquences de l'appel

L'approbation au niveau de la session est utile pour une exécution qui réalise de nombreuses lectures attendues. Demander à quelqu'un d'approuver chaque recherche de métadonnées l'habitue à cliquer sans lire. C'est une fatigue liée aux approbations, qui réduit l'attention accordée aux demandes importantes.

Mais la publication et la suppression doivent interrompre ce flux. Chacune modifie un état externe d'une manière qu'un téléchargement de dépendance courant ne modifie pas. Exigez une confirmation distincte pour une nouvelle version de paquet, une autre pour la modification d'un dist-tag et une autre pour chaque action destructive. Si l'agent propose deux publications de paquets, affichez deux demandes. Une approbation groupée masque la version exacte que la personne chargée de l'examen doit vérifier.

La demande par appel doit contenir suffisamment d'informations pour permettre de refuser l'action pour la bonne raison :

• L'hôte du registre et l'espace de noms ou le propriétaire du paquet.
• L'opération : publication, déplacement de tag, dépréciation, retrait ou suppression.
• La version exacte concernée et la transition de tag demandée.
• Le processus de l'agent qui a effectué la demande, afin que la personne chargée de l'examen puisse refuser un appelant inattendu.
• Une courte justification tirée du plan de publication, et non de la sortie libre d'un outil.

Ne demandez pas à une personne d'analyser un en-tête d'autorisation ou de comparer des hachages opaques au moment de décider. Ce sont des détails d'audit. La décision immédiate doit présenter clairement les conséquences de l'action, tandis que le système conserve la demande sous-jacente pour un examen ultérieur.

Le contrôle de clé par appel de Sallyport correspond bien à la limite de publication : l'identifiant du registre peut exiger une approbation à chaque utilisation, tandis que l'agent continue son travail courant avec une décision de session distincte. Cela ne remplace pas l'examen du contenu du paquet. Cela empêche un identifiant de publication de devenir une autorité permanente après un seul clic.

Traitez les tags comme une modification du routage vers les consommateurs

Un dist-tag peut rendre une version correcte dangereuse pour vos utilisateurs. Dans les registres compatibles avec npm, une installation sans version explicite suit généralement le tag latest. Déplacer ce tag modifie ce que reçoivent les nouvelles installations, même si le tarball déjà publié reste inchangé.

Séparez la publication et le déplacement d'un tag en deux demandes. Publiez d'abord une version candidate, puis récupérez-la par sa version exacte dans un projet de test vierge. Ce n'est qu'après cette vérification qu'une personne doit décider si latest doit changer. Vous disposez ainsi d'un temps d'arrêt utile : les octets sont visibles sous une version immuable et la décision de routage n'a pas encore été prise.

Les commandes rendent la distinction évidente :

npm publish --tag candidate
npm view @acme/widget dist-tags --json
npm dist-tag add @acme/[email protected] latest

La première commande crée une version et lui attribue un chemin candidat. La dernière modifie le chemin suivi par de nombreux utilisateurs. Un script de publication qui cache les deux opérations dans une seule fonction utilitaire supprime le moment le plus utile pour le jugement humain.

Ne laissez pas un agent corriger une erreur de tag en devinant. Si latest pointe vers la mauvaise version, l'agent doit indiquer la carte actuelle des tags, la version prévue et la correction proposée. Une personne doit la confirmer. Dans ce cas, le coût d'un clic supplémentaire est minime par rapport à celui qui consiste à envoyer un mauvais paquet à chaque nouvelle installation.

Gardez des dossiers d'audit utiles après l'incident

Un simple historique des commandes ne permet pas de savoir qui a autorisé une modification du registre, quelle exécution d'agent l'a demandée ni si quelqu'un a modifié le journal ensuite. Les opérations de publication ont besoin d'un dossier qui relie la demande, l'approbation, le résultat de l'exécution et les métadonnées renvoyées par le registre.

Consignez le nom du paquet, la version, l'hôte du registre, le type d'opération, le statut final et une référence vers l'inspection de l'artefact réalisée avant l'action. Ne consignez pas les jetons, les en-têtes d'autorisation ni les fichiers de configuration bruts susceptibles de contenir des identifiants. Un bon dossier d'audit permet à un mainteneur de répondre à une question pratique des mois plus tard : avons-nous publié cette version, déplacé un tag ou simplement tenté de le faire ?

La détection des modifications est importante, car les journaux de publication ne deviennent souvent des preuves qu'une fois le problème survenu. Sallyport conserve les événements de session et les appels individuels dans des journaux distincts, projetés depuis un journal d'audit chiffré et chaîné par hachage, et sp audit verify peut vérifier cette chaîne hors ligne sans clé de coffre. C'est plus fiable qu'un fichier texte modifiable dans le dépôt.

Les journaux ne rendent pas une action dangereuse sûre. Ils permettent de reconstituer le chemin suivi lorsqu'une demande d'approbation a été mal comprise, qu'une destination de registre était incorrecte ou qu'un processus de publication a fait quelque chose que personne n'attendait. Associez le journal à un moyen immédiat de révoquer une session d'agent en cours. Quand une publication commence à se comporter étrangement, arrêter l'appel suivant est plus utile que de rédiger plus tard un compte rendu parfait.

Intégrez le test temporaire au contrat de publication

Le test de publication temporaire doit être un contrôle planifié du chemin de publication, pas une improvisation après l'échec d'une publication de production. Définissez les situations dans lesquelles il s'exécute : modification d'une intégration de registre, changement de gestion des identifiants, adoption d'une nouvelle configuration de gestionnaire de paquets ou avant d'accorder un accès de publication à un nouveau workflow d'agent.

Gardez son autorité plus limitée que celle de la production lorsque c'est possible, mais ne le rendez pas si artificiel qu'il manquerait le véritable mode d'échec. Testez la même catégorie de registre, le même intermédiaire de requêtes, le même mode de stockage des identifiants et la même vérification d'installation propre. Si la publication en production exige une approbation humaine, le test doit l'exiger aussi. Sinon, vous testez un autre système.

La première action utile consiste à retirer les identifiants d'écriture du registre des variables d'environnement visibles par l'agent, puis à faire passer un paquet temporaire par le chemin contrôlé exact auquel vous prévoyez de faire confiance. Lisez la liste des fichiers du paquet avant l'approbation. Inspectez la version exacte après la publication. Laissez la suppression faire l'objet d'une approbation distincte, car un compte de test propre ne justifie jamais une faille accidentelle dans votre limite de publication.