MARS TECH vite-debug-plugin

À propos du projet

vite-debug-plugin est un projet à code source ouvert de MARS TECH, publié sur npm sous le scope@mars-tech sous le nom @mars-tech/vite-debug-plugin. Le code source est sur GitLab : mars-tech/vite-debug-plugin.

Notes de version de la 1.0.0

La 1.0.0 est la première version stable. $debug journalise désormais comme console.log, montre d'où vient réellement chaque appel, s'intègre à Vue DevTools et masque les secrets à davantage d'endroits. Les appels sont supprimés des builds de production de façon plus fiable.

  • Plusieurs valeurs à la fois, façon printf, dans le navigateur et dans le terminal.
  • Des objets vivants dans la console du navigateur, dépliables comme avec console.log. Ils s'affichent plutôt en texte masqué quand des motifs de masquage côté navigateur sont définis.
  • Des groupes, tableaux et vues d'objets dans la console, qui utilisent les fonctions natives de la console du navigateur.
  • Le vrai fichier:ligne de chaque appel, dans votre source d'origine, au même format src/Cart.vue:12:3 dans le navigateur, le terminal et les pages rendues côté serveur.
  • Une intégration à Vue DevTools : dans les applications Vue et Nuxt, chaque appel apparaît aussi dans un inspecteur et une chronologie MARS-TECH. Installez @vue/devtools-api pour l'activer.
  • Un fichier de log optionnel pour les outils et les assistants d'IA : une ligne JSON par appel, déjà masquée, tenue hors de git. Pour des raisons de sécurité, ne l'utilisez pas quand votre code logue des secrets, même masqués.
  • De nouvelles options : un filtre d'espaces de noms par défaut, et la pile d'appels jointe par défaut à chaque appel qui journalise une erreur.
  • Plus simple à utiliser dans les tests et l'outillage : un journaliseur de test configurable, les types publics depuis l'entrée principale, et la prise en charge d'ESLint 10.

Côté sécurité, vos secrets écrits en chaînes restent désormais sur le serveur de développement, le masquage couvre bien davantage de chaque appel, le texte journalisé ne peut plus prendre le contrôle de votre terminal, une page web ne peut plus faire planter, figer ni inonder le serveur de développement par $debug, et le code de développement n'atteint plus les builds de production par les chemins qu'il empruntait. Le masquage reste un filet de sécurité, pas un coffre-fort : ne journalisez jamais de secrets de production.

Vous passez de la 0.6.1 ? La plupart des projets n'ont besoin que de quelques options renommées. Les anciens noms d'option fonctionnent encore, avec un avertissement, jusqu'à la 2.0.0. Migrer depuis la 0.6 liste ce qu'il faut changer.

Journal des modifications

Chaque version est décrite dans le journal des modifications sur GitLab (en anglais), avec chaque correction et chaque changement incompatible.

Sécurité

La politique de sécurité sur GitLab (en anglais) fait référence. En résumé :

Signaler une faille

N'ouvrez pas de ticket public. Signalez la faille en privé : ouvrez un ticket confidentiel sur GitLab en cochant « This issue is confidential » avant de l'envoyer, ou écrivez à l'adresse indiquée dans la politique de sécurité, avec un objet qui commence par [SECURITY]. Indiquez les versions du plugin, de Vite et de Node.js, si le problème se reproduit en développement, dans un build de production ou les deux, une reproduction minimale, ce qui est exposé et à qui, et toute configuration redact ou redactDefaults en jeu.

Le projet est maintenu par une petite équipe : ce sont des objectifs, pas un engagement contractuel. Un accusé de réception sous 5 jours ouvrés, une première évaluation sous 10, et un correctif publié aussi vite que la gravité l'exige. Les personnes qui signalent une faille sont citées dans le journal des modifications, sauf si elles demandent le contraire. Laissez aux mainteneurs un délai raisonnable pour publier un correctif avant toute divulgation publique.

Versions prises en charge

Les correctifs de sécurité arrivent sur la dernière version mineure publiée de la version majeure en cours. La 1.0.x est la version prise en charge, celle des publications actuelles. La 0.6.x ne reçoit plus que des correctifs de sécurité, pendant une période de transition : passez à la 1.0. Les versions antérieures à la 0.6 ne sont pas prises en charge.

Ce qui compte comme une faille

Le plugin est un outil de développement dont le rôle est d'afficher des diagnostics. La question est de savoir s'il révèle une information à quelqu'un qui ne devrait pas la voir, ou à un endroit où elle ne devait pas aller. Entrent dans le périmètre, par exemple :

  • une règle redact ou redactDefaults qui masque une surface de sortie mais pas une autre qu'elle couvre ;
  • une entrée chaîne de redact, ou toute autre donnée que seul le processus Vite devrait détenir, qui atteint quoi que ce soit que le serveur de développement remet à une page ;
  • un appel $debug qui survit à un build de production, ou une variante library.debugBuild qui place quoi que ce soit d'imprévu dans le bundle de production d'une application consommatrice ;
  • une page qui contourne le masquage côté serveur, écrit des séquences de contrôle dans votre terminal, ou fait croître sans limite la mémoire ou le disque du serveur de développement ;
  • tout ce que le serveur de développement renvoie à une page ;
  • une exécution de code par la transformation ou le code généré du plugin.

Hors du périmètre : les diagnostics qui apparaissent dans votre propre console ou votre propre terminal pendant le développement (c'est le produit), les valeurs pour lesquelles vous n'avez configuré aucune règle de masquage, les attaques qui supposent du code non fiable déjà exécuté dans votre serveur de développement, les failles des dépendances (à signaler en amont), et tout ce qui n'est atteignable qu'en modifiant vite.config.ts. Les limites du masquage sont décrites dans Ce que le masquage couvre et ne couvre pas : une limite connue et documentée est plus utile aux mainteneurs comme demande de fonctionnalité que comme signalement de faille.

Le serveur de développement ne renvoie rien

Le plugin tient une règle sur le serveur de développement : il n'envoie jamais à l'origine de développement quoi que ce soit qui provienne d'un enregistrement de log. Il n'y a pour cela aucun point d'accès, aucun message HMR, aucun accusé de réception ni message d'erreur, aucun canal DevTools et aucun fichier servi. Les logs ne vont que du navigateur vers le serveur.

Tout script de la page de développement peut envoyer ses propres lignes de log, et le serveur de développement les masque avec vos entrées chaîne de redact, que la page n'a jamais. Si ce script pouvait relire ce que le serveur a fait de ses lignes, il saurait lesquelles de ses hypothèses ont été masquées, et retrouverait une entrée caractère par caractère. C'est pourquoi le fichier de log NDJSON est tenu hors de portée de la page. Cette protection est un filet de sécurité, pas un coffre-fort : un chemin que personne n'a encore trouvé peut toujours remettre le log à une page. N'activez pas output.file quand votre code logue des secrets, même masqués ; un log que vous gardez malgré tout a sa place hors du projet, hors de server.fs.allow (dans un monorepo, la racine de l'espace de travail), où Vite refuse tout fichier. Gardez les clés de production hors de toute configuration de développement. Le signalement d'un nouveau chemin vers un log situé dans le projet entre dans le périmètre.

Contribuer

Les contributions, rapports de bogues et demandes de fonctionnalités sont les bienvenus. Lisez le guide de contribution (en anglais) pour la mise en place de l'environnement de développement, le modèle de branches, les conventions de messages de commit (Conventional Commits), la signature DCO et la liste de vérification des merge requests.

Pour les failles de sécurité, n'ouvrez pas de ticket public : voir Sécurité.

Tickets

Signalez un bogue, proposez une fonctionnalité ou parcourez le travail en cours sur le tableau des tickets GitLab de vite-debug-plugin.

Politique de versions

Le projet suit la gestion sémantique de version 2.0.0, avec deux règles propres au projet :

  • Les changements incompatibles n'arrivent que dans une version majeure. Une option du plugin renommée continue de fonctionner pendant toute la version majeure, avec un avertissement unique qui nomme son remplaçant, et disparaît à la suivante. Une option supprimée purement et simplement déclenche un avertissement unique au lieu d'échouer en silence. Chaque changement est signalé dans le journal des modifications, et le guide de migration en donne l'extrait avant/après.
  • La plage peerDependencies.vite et le plancher engines.node font partie de l'API publique : restreindre la première ou relever le second est un changement majeur.

Licence

MIT, © MARS TECH. Voir le fichier de licence (en anglais).