Authentification et 2FA

Un compte BlockLucky s'ouvre de trois façons : avec une adresse email et un mot de passe, avec un compte Google, ou, sur le web, avec un code à usage unique reçu par email. Une fois connecté, le citoyen peut ajouter une double authentification par application TOTP ou par email. Cette page décrit les mécanismes et leurs paramètres tels qu'ils sont codés. Le fonctionnement fonctionnel du module (routes, réponses) est décrit dans le module Authentification.

Fichiers principaux :

#Vue d'ensemble

Quelle que soit la route de connexion, un compte vérifié dont la 2FA est active doit encore fournir son code TOTP ou son code email à /2fa/verify avant de recevoir un jeton (completePrimaryLogin). Pour la 2FA par application, le code n'est accepté qu'avec le ticket de connexion délivré après le premier facteur (voir Connexion d'un compte protégé par TOTP). /password/change fait exception : l'appelant a déjà une session, et le jeton de remplacement est délivré sans nouveau code. Toutes ces routes passent par authRateLimiter : 30 requêtes par adresse IP en 10 minutes.

#Mot de passe

#Politique et stockage

La politique ne vérifie ni les mots de passe compromis (aucune consultation d'une liste de fuites) ni la ressemblance avec l'email. Le mobile affiche les mêmes règles avant l'envoi (PasswordRules.tsx).

#Inscription

POST /api/auth/signup ne crée pas le compte. Il hache le mot de passe, place l'empreinte, l'email, le parrain éventuel et la source dans un défi SIGNUP stocké dans Redis, puis envoie un code à 6 chiffres. Le compte n'est créé qu'à la vérification de ce code par POST /api/auth/2fa/verify : un mot de passe ne peut donc pas être attaché à une adresse que son auteur ne contrôle pas.

Si l'adresse appartient à un compte non vérifié, par exemple créé pour le bénéficiaire d'un ticket offert, la vérification active ce compte et lui donne le mot de passe au lieu d'en créer un second (activateExistingAccount). Si elle appartient à un compte vérifié ou anonymisé, la route répond 409 « Un compte existe déjà avec cette adresse email. ».

#Connexion

POST /api/auth/signin applique trois protections :

Pour un compte existant, le compteur d'échecs est celui des codes email : des échecs de mot de passe et des codes faux s'additionnent. Comme pour les codes, un tiers peut bloquer la connexion d'un compte pendant une heure. Le test bloque le compte après 10 échecs, y compris pour une adresse inconnue couvre ce comportement.

#Réinitialisation

Le code suit les paramètres décrits dans Paramètres du code. La même route permet à un compte créé sans mot de passe d'en définir un ; l'alerte indique alors « Mot de passe défini sur votre compte ».

#Changement depuis un compte connecté

POST /api/auth/password/change exige un jeton de session valide. Si le compte a un mot de passe, currentPassword est obligatoire et comparé par bcrypt ; un échec renvoie 401 « Mot de passe actuel incorrect. » et s'ajoute au compteur d'échecs du compte, celui de /signin (10 échecs en une heure bloquent le compte pendant une heure). Un compte créé par code email ou Google peut définir un premier mot de passe sans en fournir d'ancien : la possession de la session suffit.

Un vol de session suffit donc à définir un mot de passe sur un compte qui n'en a pas, et à déconnecter le propriétaire légitime ; l'alerte par email est alors le seul signal. Pour un compte qui a déjà un mot de passe, le voleur doit aussi le connaître.

#Changement d'adresse email

Le changement se fait en deux requêtes authentifiées :

Le code envoyé à la nouvelle adresse prouve qu'elle appartient au demandeur ; l'alerte à l'ancienne adresse prévient le titulaire si la demande ne vient pas de lui. Les sessions ne sont pas révoquées par un changement d'adresse. Pour un compte sans mot de passe, la session seule suffit à demander le changement.

#Google

Le mobile obtient un jeton d'identité auprès de Google et l'envoie au backend, qui le vérifie lui-même avant toute création de compte. La connexion avec Apple a été retirée : il n'existe plus de route /oauth/apple ni de variable APPLE_CLIENT_IDS.

La liste d'identifiants est vide par défaut : la connexion Google reste donc désactivée tant qu'elle n'est pas renseignée (voir Variables d'environnement).

#Rattachement par adresse email

oauthLogin cherche le compte par l'adresse email du jeton, sans enregistrer l'identifiant sub du fournisseur.

#Connexion par code email

Ce parcours est celui du web (POST /api/auth/login). Il reste ouvert à tous les comptes, y compris à ceux qui ont un mot de passe.

#Déroulé

sequenceDiagram
    participant C as Client
    participant A as API
    participant R as Redis
    participant M as File d'emails
    C->>A: "POST /api/auth/login (email, walletAddress, isAdultConfirmed, acceptTerms)"
    A->>A: "Recherche du compte par adresse puis par email"
    A->>R: "Code haché, tentatives = 0, TTL 10 min"
    A->>M: "Email otp-code"
    A-->>C: "requiresTwoFactor, twoFactorMethod EMAIL, userId"
    C->>A: "POST /api/auth/2fa/verify (userId, code)"
    A->>R: "Comparaison en temps constant, suppression du code"
    A-->>C: "Jeton JWT et profil"

POST /api/auth/login ne délivre jamais de jeton quand LOGIN_EMAIL_CODE_REQUIRED vaut true, ce qui est la valeur par défaut et la seule acceptée en production. Le jeton n'est délivré qu'après POST /api/auth/2fa/verify. Un compte dont la 2FA est active reçoit toujours ce code email d'abord, quel que soit LOGIN_EMAIL_CODE_REQUIRED ; si sa 2FA est par application, la vérification du code email ne délivre pas encore de session mais un ticket de connexion (voir Connexion d'un compte protégé par TOTP).

Le champ walletAddress envoyé par le client sert uniquement à retrouver un compte existant. Il n'est jamais utilisé comme portefeuille : le backend crée le sien (voir Portefeuilles intégrés). Comme une adresse de portefeuille est publique sur la chaîne, elle ne prouve rien ; la preuve vient du code reçu par email.

#Paramètres du code

Le compteur d'échecs est indexé par compte, pas par adresse IP. Un attaquant qui change d'adresse IP ne contourne donc pas le blocage. En contrepartie, un tiers peut bloquer la connexion d'un compte pendant une heure en saisissant dix codes faux : le blocage est temporaire et ne demande aucune intervention humaine.

#Inscription par code

Un compte n'existe qu'une fois l'email prouvé. Pour une adresse inconnue, le backend :

1. génère un identifiant de défi aléatoire (randomUUID) ;
2. stocke dans le défi les données d'inscription (email, code de parrainage résolu, tranche d'âge, source UTM) ;
3. envoie le code.

À la vérification, createVerifiedUser crée le compte avec isEmailVerified: true, son portefeuille chiffré, les 25 EtherPoints de bienvenue et, le cas échéant, le bonus de parrainage. Aucun point n'est donc attribué à une adresse non prouvée. Le test exige le code envoyé par email avant de créer le compte et de délivrer un jeton couvre ce comportement.

La case isAdultConfirmed doit valoir true : le schéma Zod la refuse sinon. Il s'agit d'une déclaration ; la vérification d'âge effective passe par la pièce d'identité (voir Vérification d'âge). /signup exige la même déclaration, avec acceptTerms. /login accepte acceptTerms, facultatif, qui doit alors valoir true ; le web l'envoie toujours, après la case obligatoire « J'accepte les conditions générales d'utilisation et le règlement de participation ». Aucune de ces déclarations n'est enregistrée en base ; seule isAdultConfirmed figure dans les métadonnées analytiques. /signin et /oauth/google ne les demandent pas.

#Code visible en développement

Quand NODE_ENV vaut development, les réponses qui déclenchent un code email (/login, /signup, /signin avec 2FA par email, /password/forgot, /2fa/setup) contiennent devOtpPreview, la valeur du code. Ce champ n'existe ni en test ni en production.

#Double authentification TOTP

#Activation

1. POST /api/auth/2fa/setup avec { "method": "APP" } (route authentifiée).
2. Le backend génère un secret de 32 caractères base32, soit 160 bits, à partir de crypto.randomBytes(32). Comme 256 est un multiple de 32, l'opération octet % 32 n'introduit pas de biais.
3. Il enregistre le secret chiffré (encryptText, format v2:) et dix codes de secours hachés, avec isTwoFactorEnabled: false.
4. Il renvoie une seule fois le secret, l'URL otpauth://, le QR code et les codes de secours en clair.
5. Le citoyen saisit un premier code TOTP dans POST /api/auth/2fa/verify, avec sa session (jeton Bearer). Ce n'est qu'alors que isTwoFactorEnabled passe à true. Sans session, un code présenté pour un compte dont la 2FA n'est pas encore active est refusé en 401.
6. Toutes les sessions existantes sont révoquées (revokeAllForUser), un email d'alerte est envoyé et une nouvelle session est délivrée.

Une 2FA déjà active ne peut pas être reconfigurée directement : setup répond 409 et il faut d'abord la désactiver.

#Vérification

Le test refuse le rejeu d'un code TOTP déjà utilisé vérifie l'anti-rejeu.

#Codes de secours

La normalisation (normalizeBackupCode) met en majuscules et retire tout caractère non alphanumérique : abcde-fghij et ABCDEFGHIJ désignent le même code. Le hachage n'est pas salé ; avec 50 bits d'entropie par code, une attaque par dictionnaire sur une base volée reste coûteuse, mais un hachage lent (bcrypt, déjà disponible via hashValue) serait plus robuste.

#Double authentification par email

Avec { "method": "EMAIL" }, setup envoie un code de type SETUP. Sa vérification active la 2FA par email, révoque les sessions existantes et envoie une alerte. Ensuite, chaque connexion passe par le même code email que la connexion standard.

#Connexion d'un compte protégé par TOTP

Pour un compte dont twoFactorMethod vaut APP et isTwoFactorEnabled vaut true, le code de l'application n'est accepté qu'une fois le premier facteur franchi.

Le client envoie ensuite le code TOTP ou un code de secours à POST /api/auth/2fa/verify avec le corps { code, userId?, loginTicket? }.

Un code d'application n'est accepté que dans deux cas : le ticket est valide et appartient au compte visé, ou la requête porte une session (Bearer) de ce compte, ce qui sert à l'activation de la 2FA. Un ticket inconnu ou expiré, un ticket d'un autre compte que le userId envoyé, ou un code d'application présenté avec le seul userId reçoivent 401 « Connexion expirée ou incomplète : reconnectez-vous avant de saisir le code de votre application. ». Quand un ticket est fourni, un éventuel code email en attente pour le compte est ignoré. Les tests refuse un code de l'application présenté avec le seul identifiant du compte, refuse d'activer la 2FA par application sans session authentifiée et demande le code de l'application après le mot de passe, avec un ticket de connexion couvrent ces règles.

Le mobile transmet le ticket à l'écran Verify2FA (paramètre loginTicket) ; le web le garde dans pendingLoginTicket du slice auth.

#Désactivation

POST /api/auth/2fa/disable exige l'une de ces preuves :

• un code TOTP ou un code de secours valide ;
• une session de moins de 15 minutes (sessionService.isRecent).

Sans preuve, la réponse est 401 et un échec est compté. Quand la 2FA était active, un email d'alerte est envoyé. Le test exige une authentification récente pour désactiver la 2FA couvre ce cas.

#2FA obligatoire pour les administrateurs

requireRoles refuse avec 403 toute route ADMIN si le compte n'a pas isTwoFactorEnabled, tant que ADMIN_MFA_REQUIRED vaut true. Cette variable est forcée en production : le schéma de backend/src/config/env.config.ts refuse de démarrer avec false. Le contrôle lit la base à chaque requête, pas le jeton : un administrateur qui désactive sa 2FA perd l'accès aux routes ADMIN immédiatement.

#Notifications de sécurité

Le modèle backend/src/templates/emails/security-alert.html est envoyé lors des événements suivants :

#Limites connues

Autres limites relevées dans le code :

Ces points sont repris dans Points à valider et dans la synthèse des audits.