@starterlib/cli 0.11.6 → 0.12.0

package/README.md

@@ -148,3 +148,31 @@ rxjs, tslib, es-module-shims) s'admet dans `package.json`, avec sa raison ecrite
   }
 }
 ```
+
+## Admissions nommees de la garde de securite (0.11.7)
+
+Une dependance de production admise qui porte, sans reglage qui l'en retire, un motif que `securite` refuse
+(son etat dans le stockage du navigateur, l'ecriture HTML ou les styles de ses composants d'interface) s'admet
+NOMMEMENT, motif par motif, avec sa raison :
+
+```json
+{
+  "starterWeb": {
+    "securiteAdmise": {
+      "posthog-js": {
+        "motifs": ["stockage", "ecriture-html", "style-par-attribut"],
+        "raison": "Mesure du comportement apres accord aux temoins, chargee a la demande, hors du premier ecran.",
+        "dependances": []
+      }
+    }
+  }
+}
+```
+
+- motifs admissibles : `stockage`, `ecriture-html`, `insertion-html`, `style-par-attribut` ; jamais `eval`,
+  `Function`, la lecture de cookie, une politique Trusted Types ni un puits propre a un remote ;
+- le paquet doit figurer dans `dependancesAdmises` ; la raison compte au moins 40 caracteres ;
+- l'admission ne vaut que pour un morceau livre dont TOUTES les sources sont du paquet (ou des paquets nommes dans
+  `dependances`), lues dans la carte de la construction (`browser-stats.json`, `statsJson: true` sur la cible esbuild) :
+  le code de l'application reste juge en entier. Charger le paquet par un import dynamique lui donne son propre morceau ;
+- `verify` nomme chaque morceau admis, et avertit d'une admission qui ne couvre aucun morceau.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starterlib/cli",
-  "version": "0.11.6",
+  "version": "0.12.0",
   "description": "Chaine de verification et de construction des SPA du socle frontal starter : starter-web verify, construire, sprite, manifeste, precompresser. Jamais en dependance de production.",
   "license": "UNLICENSED",
   "type": "module",

package/src/etapes/securite.mjs

@@ -27,7 +27,7 @@
  * paquets construits.
  */
 import { readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 import { fichiers, lireJson, relatif } from '../commun.mjs';
 import { natureDesFichiers } from '../livraison.mjs';
 
@@ -40,7 +40,11 @@ const CREATION_DE_POLITIQUE = /trustedTypes\s*\.\s*createPolicy\(\s*['"]([^'"]*)
 const MOTIFS = [
   { motif: /\beval\(/, raison: 'eval : interdit par script-src' },
   { motif: /new Function\(/, raison: 'new Function : interdit par script-src' },
-  { motif: /localStorage|sessionStorage|indexedDB/, raison: 'stockage navigateur (ADR 0014)' },
+  {
+    id: 'stockage',
+    motif: /localStorage|sessionStorage|indexedDB/,
+    raison: 'stockage navigateur (ADR 0014)',
+  },
   { motif: /document\.cookie/, raison: 'lecture de cookie : le cookie de session est HttpOnly' },
 ];
 
@@ -59,11 +63,17 @@ const PUITS_DE_LA_SPA = [
       "bypassSecurityTrust* : la politique angular#unsafe-bypass n'est pas admise, et le desinfectant est contourne",
   },
   {
+    id: 'ecriture-html',
     motif: /\.(?:innerHTML|outerHTML)\s*=(?!=)/,
     raison: 'ecriture HTML directe : puits Trusted Types, et vecteur XSS',
   },
-  { motif: /insertAdjacentHTML\s*\(|document\.write\s*\(/, raison: 'ecriture HTML directe' },
   {
+    id: 'insertion-html',
+    motif: /insertAdjacentHTML\s*\(|document\.write\s*\(/,
+    raison: 'ecriture HTML directe',
+  },
+  {
+    id: 'style-par-attribut',
     motif: /setAttribute\(\s*["']style["']/,
     raison: "style pose par setAttribute : refuse sans 'unsafe-inline'",
   },
@@ -197,6 +207,86 @@ function jugerUnePage(nom, contenu) {
   return defauts;
 }
 
+/**
+ * Les motifs qu'une admission nommee peut lever (0.11.7) : ceux qu'une bibliotheque tierce porte sans qu'on puisse
+ * les en retirer (stockage de son etat, ecriture HTML et styles de ses composants d'interface). Jamais l'execution de
+ * chaine (`eval`, `Function`), la lecture de cookie, les politiques Trusted Types, ni les puits propres a un remote.
+ */
+export const MOTIFS_ADMISSIBLES = [
+  'stockage',
+  'ecriture-html',
+  'insertion-html',
+  'style-par-attribut',
+];
+
+/** Une raison ecrite, assez longue pour dire ce que fait le paquet et ou il se charge. */
+const RAISON_MINIMALE = 40;
+
+/** Le paquet d'un fichier source de la carte de construction : le dernier `node_modules/<paquet>/`, ou null. */
+export function paquetDeLEntree(entree) {
+  const trouves = [...entree.matchAll(/node_modules\/((?:@[^/]+\/)?[^/]+)\//g)];
+  return trouves.length === 0 ? null : trouves[trouves.length - 1][1];
+}
+
+/**
+ * Les admissions nommees d'un projet (`package.json#starterWeb.securiteAdmise`, 0.11.7) : par paquet, les motifs
+ * qu'il porte et sa raison ; `dependances` nomme les paquets qui peuvent partager ses morceaux. Le paquet doit etre une
+ * dependance de production admise (`starterWeb.dependancesAdmises`) ; un motif hors de {@link MOTIFS_ADMISSIBLES}, une
+ * raison trop courte ou un paquet inconnu est un defaut.
+ *
+ * @returns {{ admissions: Map<string, { motifs: Set<string>, paquets: Set<string> }>, defauts: string[] }}
+ */
+export function admissionsDuProjet(paquet) {
+  const declarees = paquet.starterWeb?.securiteAdmise ?? {};
+  const dependances = paquet.dependencies ?? {};
+  const revues = paquet.starterWeb?.dependancesAdmises ?? {};
+  const admissions = new Map();
+  const defauts = [];
+  for (const [nom, admission] of Object.entries(declarees)) {
+    const lieu = `starterWeb.securiteAdmise["${nom}"]`;
+    if (!(nom in dependances) || !(nom in revues)) {
+      defauts.push(
+        `${lieu} : le paquet doit etre une dependance de production admise (starterWeb.dependancesAdmises).`,
+      );
+      continue;
+    }
+    const motifs = Array.isArray(admission?.motifs) ? admission.motifs : [];
+    const horsListe = motifs.filter((motif) => !MOTIFS_ADMISSIBLES.includes(motif));
+    if (motifs.length === 0 || horsListe.length > 0) {
+      defauts.push(
+        `${lieu} : motifs ${motifs.length === 0 ? 'absents' : `hors liste (${horsListe.join(', ')})`} ; admissibles : ` +
+          `${MOTIFS_ADMISSIBLES.join(', ')}.`,
+      );
+      continue;
+    }
+    if (typeof admission.raison !== 'string' || admission.raison.trim().length < RAISON_MINIMALE) {
+      defauts.push(`${lieu} : une raison ecrite d'au moins ${String(RAISON_MINIMALE)} caracteres.`);
+      continue;
+    }
+    const compagnons = Array.isArray(admission.dependances) ? admission.dependances : [];
+    admissions.set(nom, { motifs: new Set(motifs), paquets: new Set([nom, ...compagnons]) });
+  }
+  return { admissions, defauts };
+}
+
+/**
+ * Les motifs admis pour un morceau livre : ceux d'une admission dont les paquets couvrent TOUTES les sources du
+ * morceau (lues dans la carte de la construction). Un morceau qui mele du code de l'application, ou d'un autre paquet,
+ * n'en recoit aucun : le code de l'application reste juge en entier.
+ *
+ * @returns {{ motifs: Set<string>, paquet: string | null }}
+ */
+export function motifsAdmisDuMorceau(entrees, admissions) {
+  const paquets = entrees.map(paquetDeLEntree);
+  if (paquets.length === 0 || paquets.includes(null)) return { motifs: new Set(), paquet: null };
+  for (const [nom, admission] of admissions) {
+    if (paquets.every((paquet) => admission.paquets.has(paquet))) {
+      return { motifs: admission.motifs, paquet: nom };
+    }
+  }
+  return { motifs: new Set(), paquet: null };
+}
+
 /**
  * Les defauts d'un fichier livre `nom` (relatif au dossier livre) de contenu `contenu`. `role` :
  * `remote`, `hote` ou `autonome` ; `partage` : le fichier est du code du cadre, partage par la
@@ -213,6 +303,7 @@ export function jugerUnFichierLivre(
     declarees = [],
     cadreNeutralise = false,
     orchestrateurNeutralise = false,
+    admis = new Set(),
   } = {},
 ) {
   if (cadreNeutralise) {
@@ -235,10 +326,12 @@ export function jugerUnFichierLivre(
   if (!/\.(?:m?js|html|css)$/.test(nom)) return defauts;
 
   if (!nom.endsWith('.css')) {
-    for (const { motif, raison } of MOTIFS) {
-      const tolere = EXCEPTIONS_DU_CADRE.some(
-        (exception) => exception.fichier.test(nom) && exception.motif.source === motif.source,
-      );
+    for (const { id, motif, raison } of MOTIFS) {
+      const tolere =
+        (id !== undefined && admis.has(id)) ||
+        EXCEPTIONS_DU_CADRE.some(
+          (exception) => exception.fichier.test(nom) && exception.motif.source === motif.source,
+        );
       if (!tolere && motif.test(contenu)) defauts.push(`${nom} : ${raison}.`);
     }
     for (const [, politique] of contenu.matchAll(CREATION_DE_POLITIQUE)) {
@@ -259,7 +352,8 @@ export function jugerUnFichierLivre(
 
   if (!partage) {
     const puits = role === 'remote' ? [...PUITS_DE_LA_SPA, ...PUITS_D_UN_REMOTE] : PUITS_DE_LA_SPA;
-    for (const { motif, raison } of puits) {
+    for (const { id, motif, raison } of puits) {
+      if (id !== undefined && admis.has(id)) continue;
       if (motif.test(contenu)) defauts.push(`${nom} : ${raison}.`);
     }
   }
@@ -299,6 +393,20 @@ export default {
             '(PLATFORM_WEB_CSP_TRUSTED_TYPES) : le BFF retire le remote tant qu elle n y est pas.',
       );
     const defauts = [];
+    // 0.11.7 : les admissions nommees, et la carte de la construction qui dit les sources de chaque morceau.
+    const { admissions, defauts: defautsDesAdmissions } = admissionsDuProjet(projet.paquet);
+    defauts.push(...defautsDesAdmissions);
+    const sorties =
+      admissions.size === 0
+        ? {}
+        : (lireJson(join(dirname(projet.sortie), 'browser-stats.json'))?.outputs ?? null);
+    if (sorties === null) {
+      defauts.push(
+        "starterWeb.securiteAdmise : browser-stats.json absent (statsJson: true sur la cible esbuild d'angular.json) : " +
+          'aucune admission ne se juge sans la carte de la construction.',
+      );
+    }
+    const morceauxAdmis = [];
     // Application autonome : la lecture de cookie du cadre, une seule fois dans tout le livrable.
     const autonome = projet.role === 'autonome';
     let lecturesDuCadre = 0;
@@ -314,6 +422,10 @@ export default {
       lecturesDuCadre += duCadre;
       const deLOrchestrateur = /\.m?js$/.test(nom) ? stockagesDeLOrchestrateur(contenu) : [];
       strategies.push(...deLOrchestrateur);
+      const entrees = Object.keys(sorties?.[nom]?.inputs ?? {});
+      const { motifs: admis, paquet: admisPour } = motifsAdmisDuMorceau(entrees, admissions);
+      if (admisPour !== null)
+        morceauxAdmis.push(`${nom} (${admisPour} : ${[...admis].join(', ')})`);
       defauts.push(
         ...jugerUnFichierLivre(nom, contenu, {
           role: projet.role,
@@ -321,6 +433,7 @@ export default {
           declarees,
           cadreNeutralise: duCadre === 1,
           orchestrateurNeutralise: deLOrchestrateur.length > 0,
+          admis,
         }),
       );
     }
@@ -339,6 +452,16 @@ export default {
         );
       }
     }
+    for (const nom of admissions.keys()) {
+      if (!morceauxAdmis.some((morceau) => morceau.includes(`(${nom} :`))) {
+        avertissements.push(
+          `starterWeb.securiteAdmise["${nom}"] : aucun morceau livre ne contient ce seul paquet ; l'admission ne sert a rien.`,
+        );
+      }
+    }
+    if (morceauxAdmis.length > 0) {
+      avertissements.push(`admissions nommees : ${morceauxAdmis.join(' ; ')}.`);
+    }
     return {
       defauts,
       avertissements,