Fichiers
gastinel-garde/ANNEXE-HUB.md
T
gastineltetClaude Sonnet 5.5 fb0643f0a3 GastinelGarde : signalement des detections au Hub (desactive par defaut)
Nouveau paquet hub (Java pur) : envoi asynchrone des franchissements de palier
(alerte, setback, expulsion) vers POST /internal/detections du Hub, selon la
conception du bloc 2 (section 2) et les contraintes de la revue de securite du Hub.

- fil d'envoi a part, file bornee sans verrou, copie sur disque, nouvelles tentatives
  exponentielles (1 s a 5 min), Retry-After, identifiant d'idempotence conserve ;
- le tick serveur n'ajoute qu'un objet en file : aucune entree-sortie, aucune attente ;
- cle de la source lue dans un fichier, jamais en dur, jamais journalisee ;
- champs conformes au Hub (controle, dimension, version_mod, exemptions), aucune IP ;
- reglages [hub] (envoi = false par defaut), commande /garde hub, ANNEXE-HUB.md ;
- 55 tests unitaires hors ligne (faux serveur HTTP local).

Non compile avec NeoForge ici (Garde, GardeSpec, GardeCommands) : a verifier au build.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-20 02:42:52 +02:00

Brut Annotations Historique

Annexe : contrat d'envoi des détections au Hub (GastinelGarde, branche feat/signalement-hub)

Source du contrat : conception-hub-bloc2-20261019.md §2, plus la revue de sécurité du Hub (branche feat/sanctions-bloc2, fichier stacks/accounts/internal/sanctions/ingest.go). Aucune valeur secrète dans ce fichier.

Ce que fait GastinelGarde

  • Désactivé par défaut : [hub] envoi = false. Sans cela, Signalement.surVerdict ne fait qu'une lecture de variable.
  • Quoi : un franchissement de palier (ALERTE, SETBACK ou EXPULSION) par joueur et par contrôle, pas chaque infraction, et jamais un bannissement. Un même palier n'est pas répété pendant episodeMinutes (10) ; seul un palier plus haut repart.
  • ENFORCE seulement par défaut. OBSERVE seulement si envoyerObserve = true ; ces détections portent mode = observe (le Hub ne doit jamais les compter).
  • Gravité : ALERTE = 1, SETBACK = 2, EXPULSION = 3. En ENFORCE, c'est la sanction réellement appliquée ; en OBSERVE, le palier mérité.
  • Quand : dans un fil à part (GastinelGarde-Hub, priorité basse). Le tick ajoute un objet dans une file sans verrou.
  • Où : POST <url>/internal/detections, Content-Type: application/json, en-tête X-Source-Cle: <clé>. Pas de redirection suivie.
  • Clé : lue dans fichierCle (une ligne, 32 à 256 caractères ASCII visibles, droits 600 conseillés). Jamais dans la configuration, jamais journalisée, jamais écrite dans la file sur disque.
  • Reprise sur panne : file bornée (fileMax = 10 000, les plus anciennes sont abandonnées), copie sur disque à l'arrêt et en panne, relue au démarrage ; attente 1 s, 2 s, 4 s … 5 min (+ 25 % au hasard) ; Retry-After respecté (5 min au plus) ; 401 / 403 : nouvel essai toutes les 5 min ; 400 : lot abandonné ; 413 : lot divisé par deux ; détections de plus de 23 h abandonnées (le Hub refuse au-delà de 24 h).
  • Débit : debitMaxParMinute = 50 (le Hub accepte 60 par défaut) ; lots de 50 au plus et 15 000 octets (le Hub refuse 16 Kio).

Corps envoyé

{"detections":[{
  "id_externe":"<uuid joueur>:<contrôle>:<palier>:<ms>",
  "sujet":{"type":"uuid_minecraft","valeur":"<uuid joueur>"},
  "type":"<contrôle>", "gravite":1, "mode":"enforce", "points":9.5,
  "survenue_le":"2026-10-19T10:00:00Z",
  "details":{"controle":"…","palier":3,"exemptions":["…"],"version_mod":"0.3.2","x":0,"y":0,"z":0,"dimension":"minecraft:overworld"}
}]}

Aucun champ service ni source (le Hub les déduit de la clé). id_externe est fixé à la création : toutes les tentatives d'une même détection portent le même identifiant (idempotence côté Hub).

Conformité aux contraintes du Hub

Champ Motif Hub Côté mod
type ^[a-z0-9_-]{1,48}$, dans types_autorises de la source identifiants des contrôles (killaura-angle, no-fall…)
id_externe ^[A-Za-z0-9:._-]{8,128}$ vérifié à la création
details.controle, details.dimension ^[a-z0-9_.:-]{1,64}$ minuscules, autre caractère remplacé par _, 64 au plus
details.version_mod ^[0-9A-Za-z.+-]{1,32}$ autre caractère remplacé par -, « inconnue » si impossible
details.exemptions 10 au plus, chacune ^[a-z0-9_.-]{1,32}$ nettoyées, doublons retirés
details.palier entier 0 à 100 rang de la sanction (ALERTE 2, SETBACK 3, EXPULSION 4)
details.x/y/z entiers ±30 000 000 position arrondie au bloc, seulement si coordonnees = true
texte aucune adresse IPv4 / IPv6 / préfixe mêmes motifs que le Hub ; une valeur qui en ressemble est omise
points 0 à 99 999 borné
survenue_le RFC 3339, de −24 h à +5 min heure serveur, secondes
autre clé de details retirée par le Hub liste blanche appliquée aussi à la création et à la relecture du disque

Le texte libre du moteur (Verdict.details(), qui peut contenir un pseudo) n'est jamais envoyé.

À aligner avec le Hub (hypothèses du mod, à confirmer quand la route HTTP du Hub sera écrite)

  1. Enveloppe : {"detections":[…]}. Le Hub (Service.Ingerer) prend un tableau de détections mais la route HTTP n'était pas encore écrite à la lecture ; si elle attend un tableau nu, changer EnvoiHub.envoyer (une ligne).
  2. Réponse 200 : tableau d'objets {id_externe, statut: cree|doublon|refuse, code} ; le mod accepte un tableau à la racine ou sous resultats / results / detections / items. Une réponse 200 illisible est tenue pour acceptée.
  3. details.palier : le Hub veut un entier ; le mod envoie le rang de l'énumération Sanction. À confirmer.
  4. types_autorises de la source gastinelgarde : doit contenir les 15 contrôles (Signalement.typesAttendus() donne la liste). gravite_max ≥ 3.
  5. Restriction réseau (D5-B) : côté Hub, par réseau Docker du conteneur Minecraft ; rien à faire dans le mod.