H· Hawiyati Documentation
Documentation Hawiyati

KYC et vérification d'identité

Gouvernance du niveau d'assurance, flux de vérification documentaire, états de session KYC, documents pris en charge et opérations d'administration.

Documentation Hawiyati

Gouvernance du niveau d'assurance, flux de vérification documentaire, états de session KYC, documents pris en charge et opérations d'administration.

Vue d'ensemble

La vérification KYC (Connaissance du client) est le mécanisme par lequel Hawiyati élève le niveau d'assurance identitaire d'un utilisateur. Le niveau d'assurance est stocké exclusivement dans kyc_profiles.current_level — jamais dans users.assurance_level, qui est déprécié.

Source de vérité unique kyc_profiles.current_level est la seule source faisant autorité pour le niveau d'assurance. Toute lecture du niveau d'assurance doit passer par KycGateService.effectiveLevelFor(username).

Niveaux d'assurance L0–L4

Hawiyati définit cinq niveaux d'assurance alignés sur le NIST SP 800-63A-4. Le type Java correspondant est IdentityAssuranceLevel (enum avec satisfies(), fromString() et capAtFreezeLevel()). Les valeurs inconnues échouent à fermeture sur L0.

NiveauNomPreuves requisesStatut
L0 Non vérifié Confirmation par e-mail ou téléphone uniquement — aucun document d'identité. Niveau par défaut à l'inscription. Actif
L1 Auto-déclaré Nom, date de naissance, adresse fournis et cohérents ; aucune preuve documentaire requise. Actif
L2 Vérification documentaire Document d'identité émis par l'État : CIN algérienne, passeport ou permis de conduire. Champs extraits par OCR passant les contrôles de cohérence. Empreinte du document stockée. Actif
L3 Vérification biométrique Vérification documentaire + détection de présence et correspondance faciale avec la puce ou la photo de référence. Gelé — pas encore en production
L4 Supervision en personne Toutes les preuves L3 collectées par un agent habilité dans un environnement contrôlé avec traçabilité de la chaîne de garde. Gelé — pas encore en production
Gel L3/L4 KycDecisionService.approve() refuse de définir kyc_profiles.current_level au-delà de L2 jusqu'à l'approbation d'une intégration biométrique de niveau production. Le plafond est appliqué par IdentityAssuranceLevel.capAtFreezeLevel(). Toute session demandant L3 ou L4 atteint au maximum L2 et est orientée vers une révision manuelle.

Source de vérité

DonnéeStockage faisant autoritéNe jamais utiliser
Niveau d'assurancekyc_profiles.current_levelNon users.assurance_level
Clé d'identité sourceusers.external_id + users.source_instance_idNon une colonne nullable scim_external_id
Session de complétionTable DB identity_completion_session (hash HMAC-SHA256)Non un attribut booléen kycRequired sur WebSession
Déduplication de documentsdocument_fingerprint.fingerprint (HMAC-SHA256 des champs normalisés)Non SHA-256 du fichier (vulnérable au recadrage)

Aperçu du flux de vérification

Parcours KYC client
Le flux KYC guide l'utilisateur de la capture documentaire à la décision d'approbation.

Un flux KYC commence lorsqu'un utilisateur authentifié ne satisfait pas le niveau d'assurance minimum requis par le fournisseur de services (SP). Hawiyati émet un jeton de complétion et redirige l'utilisateur vers le portail KYC.

1
Détection de la porte KYC

Après authentification réussie, KycGateService.effectiveLevelFor(username) compare le niveau actuel au minimum requis par le SP. Si insuffisant, un jeton de complétion (TTL 15 min, usage unique) est émis.

2
Capture du document

L'utilisateur télécharge les faces recto et/ou verso de son document d'identité. Le serveur calcule l'empreinte HMAC-SHA256 et vérifie les doublons.

3
Traitement OCR/MRZ

Le moteur OCR extrait les champs textuels. Si une zone de lecture machine (MRZ) est présente, les champs MRZ sont validés croisés avec les champs visuels.

4
Évaluation du score de confiance

Le moteur de décision calcule un score de confiance. Un score élevé déclenche une approbation automatique ; un score faible ou une alerte de doublon bascule en révision manuelle.

5
Révision humaine (si requise)

Un agent de vérification examine le dossier et approuve ou rejette. L'approbation met à jour kyc_profiles.current_level et invalide le jeton de complétion.

KYC de base — L1 (Auto-déclaré)

L'utilisateur fournit des informations personnelles de base : nom, prénom, date de naissance et adresse. Aucune pièce justificative n'est requise. Hawiyati vérifie la cohérence interne des données.

1
Soumission du formulaire

Nom, prénom, date de naissance, adresse de résidence.

2
Contrôle de cohérence

Vérification que la date de naissance est plausible, que l'adresse est complète.

3
Mise à jour du profil

kyc_profiles.current_level passe à L1. Événement d'audit KYC_LEVEL_UPDATED émis.

KYC standard — L2 (Vérification documentaire)

L'utilisateur soumet un document d'identité délivré par l'État. Le système extrait les données par OCR, valide la zone MRZ le cas échéant, et calcule une empreinte de déduplication.

1
Sélection du type de document

CIN algérienne (recto + verso), passeport algérien ou étranger (page photo), permis de conduire algérien (recto + verso).

2
Téléchargement des images

Maximum 10 Mo par face. Formats acceptés : JPEG, PNG, PDF. La face verso est obligatoire pour les documents à deux faces.

3
Traitement OCR et validation MRZ

Les champs OCR sont croisés avec les données MRZ (TD1 pour la CIN, TD3 pour les passeports). Les incohérences abaissent le score de confiance.

4
Contrôle d'empreinte de document

HMAC-SHA256 de (pays|type|numéro) normalisés. Un doublon avec un autre utilisateur déclenche une révision manuelle — il ne constitue pas un rejet automatique.

5
Décision automatique ou manuelle

Score élevé → approbation automatique → L2. Score faible → MANUAL_REVIEW_REQUIRED → décision d'un agent.

Niveaux L3/L4 — Gelés

Les niveaux L3 (vérification biométrique) et L4 (supervision en personne) sont définis dans le système mais ne sont pas encore en production. Toute demande d'élévation vers L3 ou L4 est plafonnée à L2 par IdentityAssuranceLevel.capAtFreezeLevel().

Comportement du gel
  • Une session KYC demandant L3 obtient au maximum L2.
  • L'agent déclarant L4 est redirigé vers la révision manuelle au maximum L2.
  • Aucune exception n'est levée — le gel est silencieux et traçable via l'événement d'audit.

États de session KYC

Chaque tentative de vérification crée une KycVerificationSession indépendante. Les transitions illégales sont bloquées par la machine d'état.

ÉtatSignificationTransitions autorisées
PENDINGSession créée ; en attente du téléchargement du document→ DOCUMENT_UPLOADED
DOCUMENT_UPLOADEDFichier reçu ; traitement OCR en file d'attente→ PROCESSING
PROCESSINGExtraction OCR/MRZ en cours→ DOCUMENT_VALIDATED, → PROCESSING_FAILED
DOCUMENT_VALIDATEDChamps extraits ; moteur de décision en évaluation→ MANUAL_REVIEW_REQUIRED, → APPROVED (automatique uniquement)
MANUAL_REVIEW_REQUIREDScore de confiance faible ou alerte doublon ; en attente d'un agent→ APPROVED, → REJECTED
APPROVEDTerminal — identité prouvée ; kyc_profiles.current_level mis à jour— (terminal)
REJECTEDTerminal — preuves insuffisantes ; l'utilisateur peut démarrer une nouvelle session— (terminal, nouvelle session autorisée)
PROCESSING_FAILEDErreur système OCR ; l'utilisateur peut réessayer→ PENDING (nouvelle tentative)

États du profil utilisateur (visibles par l'utilisateur)

ÉtatSignification
NOT_STARTEDAucune vérification initiée
IN_PROGRESSSession active en cours de traitement
DOCUMENT_SUBMITTEDDocument soumis, en attente de traitement
UNDER_REVIEWEn révision manuelle par un agent
APPROVEDIdentité vérifiée au niveau d'assurance cible
REJECTEDVérification échouée — nouvelle soumission possible
EXPIREDSession expirée sans soumission — nouvelle session requise
REVERIFICATION_REQUIREDUn administrateur a demandé une nouvelle vérification

Documents pris en charge (production)

Conformes à la norme ICAO 9303. Seuls les documents ci-dessous sont pris en charge en production. Les autres types de documents retournent une erreur de validation.

DocumentPaysFaces à capturerMRZTaille max
CIN algérienneDZARecto + Verso (obligatoire)TD1 (3 lignes)10 Mo par face
Passeport algérienDZAPage photo/données uniquementTD3 (2 lignes)10 Mo
Passeport étrangerTout paysPage photo/données uniquementTD3 (2 lignes)10 Mo
Permis de conduire algérienDZARecto + Verso (obligatoire)Aucun10 Mo par face
Promotion en laboratoire en attente Le pipeline OCR/MRZ avancé (lab/ocr-mrz-test) n'est pas encore promu dans hawiyati-kyc. Ces fonctionnalités ne sont pas documentées comme supportées en production tant que la promotion n'est pas confirmée.

Validation OCR et MRZ

Le moteur OCR extrait les données textuelles des images de documents. Pour les documents munis d'une zone MRZ (Machine Readable Zone), les champs extraits par OCR sont croisés avec les champs MRZ décodés.

Formats MRZ pris en charge

FormatLignesLargeurDocuments
TD1330 caractèresCIN algérienne
TD3244 caractèresPasseports

Contrôles de validation

  • Checksum MRZ (algorithme de pondération 7-3-1)
  • Cohérence date de naissance OCR ↔ MRZ (tolérance ±1 jour pour variations OCR)
  • Cohérence numéro de document OCR ↔ MRZ
  • Date d'expiration : document non expiré au moment de la soumission
  • Code pays ISO 3166-1 alpha-3 valide dans la MRZ

Empreinte du document (HMAC-SHA256)

Lors de la capture d'un document, Hawiyati calcule une empreinte HMAC-SHA256 de l'identité normalisée du document — pays, type de document et numéro. Cette empreinte est stockée dans document_fingerprint (schéma : hawiyati_identity).

Une correspondance de doublon est un signal de risque qui oriente la session vers la révision manuelle. Ce n'est pas un rejet automatique, car des scénarios légitimes existent (réutilisation du document après changement de nom).

Algorithme de normalisation

String normalized = (country.toUpperCase().trim()
    + "|" + docType.toUpperCase().trim()
    + "|" + docNumber.trim().toUpperCase())
    .replaceAll("\\s+", "");

Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(hmacKey, "HmacSHA256"));
String fingerprint = HexFormat.of().formatHex(
    mac.doFinal(normalized.getBytes(StandardCharsets.UTF_8)));

Comportement de détection de doublon

ScénarioAction
Empreinte correspondant à un utilisateur différentPositionner duplicateDocumentRisk=true, passer à MANUAL_REVIEW_REQUIRED. Ne pas rejeter automatiquement.
Empreinte correspondant au même utilisateurAutoriser — même utilisateur qui réessaie ou met à jour sa soumission.
Aucune empreinte existanteEnregistrer la nouvelle empreinte. Continuer la validation automatique.

Gestion des clés

La clé HMAC est injectée depuis la configuration (hawiyati.kyc.document-fingerprint-key, clé 256 bits encodée en base64). La colonne key_version dans document_fingerprint permet la rotation des clés.

Détection de présence et selfie (L3 — Gelé)

Fonctionnalité gelée — non disponible en production La détection de présence et la correspondance faciale sont requises pour L3. Ces fonctionnalités sont définies dans l'architecture mais ne sont pas disponibles avant l'approbation d'une intégration biométrique de niveau production.

Lorsque cette fonctionnalité sera disponible, le flux L3 ajoutera :

  • Capture d'un selfie vidéo court (défi de mouvement)
  • Détection de présence anti-spoofing (détection d'attaque par présentation)
  • Correspondance faciale entre le selfie et la photo du document ou de la puce

Porte de révision humaine

Les sessions en état MANUAL_REVIEW_REQUIRED sont placées dans la file d'attente de révision de la console d'administration. Un agent habilité examine les preuves et approuve ou rejette.

Déclencheurs de révision manuelle

  • Score de confiance OCR inférieur au seuil d'approbation automatique
  • Alerte de doublon de document (empreinte correspondant à un autre utilisateur)
  • Niveau d'assurance demandé ≥ L3 (plafonnement au gel)
  • Incohérence entre les données OCR et MRZ dépassant la tolérance
  • Document expiré ou pays non pris en charge
L'approbation manuelle ne peut élever le niveau qu'à L2 Même lors d'une révision manuelle, KycDecisionService.approve() applique le plafond de gel. Un agent ne peut pas accorder L3 ou L4 tant que l'intégration biométrique de production n'est pas approuvée.

Logique d'approbation

Lorsqu'un agent ou le système automatique approuve une session :

1
Résoudre le niveau atteint

IdentityAssuranceLevel.capAtFreezeLevel(requested) — les demandes L3/L4 deviennent L2.

2
Mettre à jour uniquement le profil KYC

Écrire dans kyc_profiles.current_level — jamais dans la table users. Uniquement une montée en niveau, jamais une rétrogradation via ce chemin.

3
Émettre l'événement d'audit

KYC_APPROVED avec le niveau atteint, l'identifiant de l'agent et l'identifiant de session.

4
Invalider le jeton de complétion

Tout jeton de complétion ouvert pour cet utilisateur est invalidé. La prochaine connexion se passe sans porte KYC si le niveau effectif ≥ minimum SP.

Opérations d'administration KYC

Les administrateurs peuvent effectuer des opérations de cycle de vie sur les profils KYC via les points de terminaison REST de hawiyati-admin.

Aucune élévation forcée du niveau d'assurance L'API d'administration ne permet que la rétrogradation, l'invalidation et les demandes de revérification. Un administrateur ne peut jamais définir le niveau d'assurance d'un utilisateur plus haut qu'il ne l'est actuellement via l'API. L'élévation du niveau doit provenir d'une session KYC complétée avec des preuves vérifiées.
Point de terminaisonRôle requisAction
POST /api/v1/users/{id}/kyc/invalidate ROLE_SUPER_ADMIN Rétrograder kyc_profiles.current_level au niveau cible. Refusé si cible > actuel. Événement KYC_INVALIDATED émis.
POST /api/v1/users/{id}/kyc/request-reverification ROLE_ADMIN Marquer le profil avec reverificationRequired=true et code de raison. La prochaine connexion déclenche la porte KYC. Événement KYC_REVERIFICATION_REQUESTED émis.

Notifications

Les notifications KYC sont écrites dans la table notification_outbox dans la même transaction que l'action déclenchante. Un service de distribution en arrière-plan les envoie avec relance exponentielle.

ÉvénementModèle de notificationDestinataire
Session KYC crééekyc-session-started-v1Utilisateur
Session approuvéekyc-approved-v1Utilisateur
Session rejetéekyc-rejected-v1Utilisateur
Revérification demandéekyc-reverification-required-v1Utilisateur

Conservation et suppression des données

DonnéeConservationMécanisme de suppression
Images de documents téléchargées90 jours après la décision finaleTâche planifiée de suppression
Résultats OCR (champs textuels)Durée de vie du profil utilisateurSuppression en cascade lors de la suppression du compte
Empreintes de documentsDurée de vie du profil utilisateurSuppression en cascade
Événements d'audit KYC7 ans (exigence réglementaire)Archivage uniquement — pas de suppression
Jetons de complétion15 minutes (TTL)Expiration automatique + nettoyage planifié

Alignement NIST SP 800-63A

Niveau HawiyatiIAL NISTCorrespondance
L0IAL1Auto-affirmé — aucune preuve d'identité
L1IAL1Attributs auto-déclarés, cohérence vérifiée
L2IAL2Preuve documentaire à distance — pièce d'identité émise par l'État
L3IAL2+Preuve documentaire + biométrie (gelé)
L4IAL3Supervision en personne par un agent habilité (gelé)

Responsabilités du client

Hawiyati fournit la plateforme de vérification KYC. Le client (l'organisation déployant Hawiyati) est responsable de :

  • Définir les politiques d'assurance minimale par SP en fonction de ses obligations réglementaires
  • Former les agents de révision manuelle aux procédures de vérification documentaire
  • Configurer les durées de conservation des données conformément aux exigences locales
  • Obtenir le consentement éclairé des utilisateurs avant la collecte de données biométriques
  • Notifier les autorités réglementaires compétentes en cas de violation de données affectant les dossiers KYC
  • Archiver les journaux d'audit KYC conformément aux exigences de durée de conservation applicables