SIRH/docs/superpowers/specs/2026-06-24-audit-log-forensic-context-design.md

Contexte forensique dans le journal d'activité

Date : 2026-06-24 Branche : feature/SIRH-41-ajouter-plus-d-info-dans-le-journal-d-activite

Problème

Le journal d'activité (audit_logs) ne stocke comme « qui » que le username. Or certains comptes sont partagés par plusieurs personnes (ex. compte « Usine »). Sous un compte partagé, toutes les actions apparaissent sous le même nom → impossible de distinguer les intervenants en cas de litige. Les utilisateurs se connectent aussi depuis des smartphones.

Objectif

Ajouter du contexte forensique automatique à chaque entrée du journal, sans rien demander à l'utilisateur. But : disposer d'assez d'indices techniques pour enquêter (IP, type d'appareil/OS/navigateur, identifiant d'appareil stable, User-Agent brut) et distinguer les appareils derrière un compte partagé.

Non-objectif (volontairement exclu) : identification explicite de la personne physique (liste de noms, PIN…). Écarté par l'utilisateur — on reste sur du signal automatique.

Périmètre

Inclus :

• Capture automatique de 4 signaux à chaque écriture d'audit.
• 4 nouvelles colonnes nullable sur audit_logs + migration (avec down()).
• Service UserAgentParser (libellé appareil lisible, sans dépendance externe).
• Front : identifiant d'appareil persistant (localStorage) envoyé en header sur toutes les requêtes API.
• Exposition des 4 champs dans l'API de lecture du journal (AuditLogResource / provider) pour que la future refonte d'écran les ait à disposition.
• Config framework.trusted_proxies documentée (conservatrice, à activer selon l'infra).
• Docs (doc/audit-logging.md, documentation-content.ts, CLAUDE.md) + tests unitaires.

Exclu (étape suivante) :

• Refonte de l'écran frontend/pages/audit-logs.vue (affichage des nouvelles colonnes, filtre par appareil). L'utilisateur prévoit de revoir cet écran séparément. On se contente d'exposer les données via l'API ; aucune modif du composant Vue dans ce lot.

Architecture

Capture — un seul point d'entrée

Toutes les écritures d'audit passent par AuditLogger::log() (src/Service/AuditLogger.php). On y injecte RequestStack. À chaque log(), on lit la requête courante et on renseigne les 4 champs sur l'entité AuditLog avant persistance. Aucun processor à modifier.

Extraction depuis la requête :

• ip_address ← Request::getClientIp()
• user_agent ← header User-Agent (brut)
• device_label ← UserAgentParser::parse(userAgent)
• device_id ← header X-Device-Id

Si aucune requête courante (ex. commande CLI / cron), les 4 champs restent null (comportement « system » déjà existant pour le username).

Modèle de données — audit_logs

Ajout de 4 colonnes nullable (pas de backfill, l'existant reste valide) :

Colonne	Type	Contenu
ip_address	VARCHAR(45)	IP source. 45 = longueur max IPv6 (avec mapping IPv4).
user_agent	TEXT	User-Agent brut, stocké tel quel.
device_label	VARCHAR(255)	Libellé lisible, ex. Mobile · Android · Chrome.
device_id	VARCHAR(64)	UUID persistant fourni par le front.

Migration Doctrine avec down() supprimant les 4 colonnes. Pas de nouvel index dans ce lot (le filtre par appareil étant reporté à la refonte d'écran).

Service UserAgentParser

Nouveau service src/Service/UserAgentParser.php, maison, sans dépendance. parse(?string $userAgent): ?string → libellé court composé de :

• Type : Mobile / Tablette / Ordinateur (détecté sur tokens Mobile, Tablet, iPad…).
• OS : Android / iOS / Windows / macOS / Linux / autre.
• Navigateur : Chrome / Safari / Firefox / Edge / autre (ordre de test important : Edge avant Chrome, Chrome avant Safari, car les UA s'imbriquent).

Format : Type · OS · Navigateur (ex. Ordinateur · Windows · Firefox). Retourne null si User-Agent vide. Heuristique volontairement simple et lisible ; suffisant pour distinguer mobile/poste et familles d'OS. (Alternative écartée : librairie matomo/device-detector — plus précise mais lourde et non nécessaire ici.)

Front — identifiant d'appareil persistant

• Composable frontend/composables/useDeviceId.ts : côté client uniquement, lit localStorage['sirh-device-id'] ; si absent, génère crypto.randomUUID() et le persiste. Retourne l'ID (ou null côté serveur en SSR).
• frontend/composables/useApi.ts, fonction request() (point unique de construction des headers) : headers.set('X-Device-Id', deviceId) quand l'ID est disponible. Appliqué à toutes les méthodes (GET/POST/PUT/PATCH/DELETE).
• Note : l'auth est par cookie JWT (credentials: 'include'), donc le device ID n'est pas lié à l'auth — localStorage est ici un usage non sensible, acceptable.
• Limite assumée : l'ID est par navigateur/appareil, pas par personne. Sur un poste partagé (même navigateur), l'ID est identique pour tous → distingue les appareils, pas les humains. Cohérent avec l'objectif forensique.

API de lecture

Exposer ipAddress, userAgent, deviceLabel, deviceId dans la sortie de lecture du journal (src/ApiResource/AuditLogResource.php + sérialisation dans AuditLogProvider), ainsi que dans le DTO front frontend/services/dto/audit-log.ts. Aucune modif du composant audit-logs.vue (refonte ultérieure). Objectif : les données sont prêtes à être affichées par la future refonte.

Trusted proxies (IP fiable)

framework.trusted_proxies n'est pas configuré aujourd'hui. Derrière un reverse proxy (nginx/traefik), getClientIp() renvoie l'IP du proxy. Architecture de déploiement non confirmée → on prévoit dans config/packages/framework.yaml une entrée commentée et documentée (avec exemple trusted_proxies réseau privé / loopback + trusted_headers), à activer selon l'infra. En attendant, l'IP est stockée telle que renvoyée par Symfony.

Stratégie de test

• tests/.../UserAgentParserTest : table de User-Agents réels (Chrome desktop, Safari iPhone, Chrome Android, Firefox, Edge, UA vide/null) → libellés attendus.
• tests/.../AuditLoggerTest : avec un RequestStack peuplé d'une Request factice (IP, headers User-Agent + X-Device-Id), vérifier que l'AuditLog persisté porte bien les 4 champs ; et qu'avec une RequestStack vide (contexte CLI), les 4 champs sont null.

Documentation à mettre à jour (règles obligatoires CLAUDE.md)

• doc/audit-logging.md : section « Données stockées par entrée » + nouveaux champs + note sur le device ID front et le caveat trusted proxies.
• frontend/data/documentation-content.ts : doc in-app (niveau admin) du journal.
• CLAUDE.md : section Audit Logging — mentionner les 4 nouveaux signaux et le point de capture unique (AuditLogger + RequestStack).

Risques / limites

• Device ID = par appareil, pas par humain (cf. ci-dessus).
• IP peu utile derrière proxy tant que trusted_proxies n'est pas activé.
• Plusieurs personnes dans la même usine sortent souvent sur la même IP publique et peuvent avoir le même modèle de téléphone → les signaux se recoupent ; ce lot fournit des indices, pas une preuve d'identité.