Securité & Cryptographie

Copy of sumaris-pod/.agents/rules/security-and-crypto.md (rule written for AI coding agents, when implementing authentication, authorization, access control, or cryptographic operations). Do not edit here: run npm run site:sync-rules to update it.

Spring Security

• La sécurité des méthodes repose sur Spring Security et l'annotation @Secured.
• Le projet fournit des méta-annotations dans le package net.sumaris.server.http.security pour simplifier le contrôle d'accès :

Annotation	Rôles autorisés	Usage
@IsAdmin	ROLE_ADMIN	Réservé aux administrateurs
@IsSupervisor	ROLE_SUPERVISOR, ROLE_ADMIN	Superviseurs et administrateurs
@IsUser	ROLE_USER, ROLE_SUPERVISOR, ROLE_ADMIN	Tout utilisateur authentifié (hors guest)
@IsGuest	ROLE_GUEST, ROLE_USER, ROLE_SUPERVISOR, ROLE_ADMIN	Tout utilisateur authentifié (y compris guest)

• Applique ces annotations sur les méthodes de service ou les classes entières (@Target({ METHOD, TYPE })).
• Préfère toujours ces méta-annotations plutôt que @Secured directement, pour garantir la cohérence des rôles.
• Pour les vérifications programmatiques (dans les contrôleurs REST, etc.), utilise AuthService.isLogin() et AuthService.hasAuthority().

Contrôle d'accès fin via DataAccessControlService

• Pour un contrôle d'accès plus granulaire (par programme de collecte, lieux, dates, etc.), utilise DataAccessControlService (package net.sumaris.server.service.administration).
• Ce service permet de vérifier et filtrer les droits d'un utilisateur selon :
  • Programmes de collecte : getAuthorizedProgramIds(), getAuthorizedProgramIdsByUserId(), getAllAuthorizedProgramIds().
  • Lieux (locations) : getAuthorizedLocationIds(), getAuthorizedLocationIdsByUserId().
  • Données (lecture/écriture) : checkCanRead(), checkCanWrite(), checkCanReadAll(), checkCanWriteAll() — vérifient les droits sur des objets IRootDataVO.
  • Accès aux données d'autres utilisateurs : canUserAccessNotSelfData(), canDepartmentAccessNotSelfData().
• Utilise la constante DataAccessControlService.NO_ACCESS_FAKE_IDS pour indiquer l'absence totale d'accès (valeur sentinelle -999).
• Ce service est typiquement injecté dans les GraphQLService et les contrôleurs REST pour appliquer les filtres d'accès avant de déléguer aux services métier.
• Exemple d'utilisation dans un GraphQLService :

  // Vérifier les droits en écriture
  dataAccessControlService.checkCanWrite(trip);
  
  // Filtrer les programmes autorisés
  Integer[] authorizedProgramIds = dataAccessControlService.getAuthorizedProgramIds(filter.getProgramIds())
      .orElse(DataAccessControlService.NO_ACCESS_FAKE_IDS);
  filter.setProgramIds(authorizedProgramIds);
  

Crypto & keys

• Les termes issuer/sender désignent une clef publique (ED25519).
• Pour le système lui‑même, utilise la valeur spéciale SYSTEM plutôt qu’une clef dédiée.
• Le serveur possède sa propre paire de clefs (pub/priv) pour signer des documents.
• Ne laisse jamais de chaîne codée en dur pour les entités système — utilise SystemRecipientEnum.
• Pour l’affichage des clé publique (pubkey) utilise CryptoUtils.minifyPubkey() et résous les informations via PersonService puis Persons.getDisplayName().