Ajout des commentaires dans le code

app/Core/Csrf.php

@@ -4,8 +4,21 @@ declare(strict_types=1);
 
 namespace App\Core;
 
+/**
+ * Jeton anti-CSRF, transporté dans le corps JSON et non dans un en-tête.
+ *
+ * Le jeton est publié dans window.PTA_CONFIG.csrfToken par layouts/footer.php ;
+ * le JS le recopie dans chaque charge utile mutante sous la clé « csrf_token ».
+ * Ce choix évite d'avoir à gérer une requête préliminaire CORS et garde les
+ * appels fetch() identiques d'un module à l'autre.
+ */
 final class Csrf
 {
+    /**
+     * Renvoie le jeton de la session courante, en le créant au premier appel.
+     * Le jeton vit aussi longtemps que la session : il n'est pas renouvelé à
+     * chaque requête, sans quoi deux onglets ouverts s'invalideraient l'un l'autre.
+     */
     public static function ensureToken(): string
     {
         Session::start();
@@ -17,12 +30,21 @@ final class Csrf
         return (string) $_SESSION['csrf_token'];
     }
 
+    /**
+     * Vérifie le jeton d'une charge utile et interrompt la requête si besoin.
+     *
+     * À appeler en tête de TOUT endpoint mutant, sans exception. La comparaison
+     * passe par hash_equals() pour ne pas être sensible au temps d'exécution.
+     *
+     * @param array<string, mixed> $payload Corps JSON déjà décodé.
+     */
     public static function assertPayload(array $payload): void
     {
         $expected = self::ensureToken();
         $provided = (string) ($payload['csrf_token'] ?? '');
 
         if ($provided === '' || !hash_equals($expected, $provided)) {
+            // send() termine le script : rien ne s'exécute après ce point.
             JsonResponse::send(403, ['error' => 'Jeton de sécurité invalide. Rechargez la page.']);
         }
     }