Services transverses

Le dossier backend/src/services contient les services partagés par plusieurs modules métier. Ce sont des classes instanciées une seule fois et exportées par défaut. Ils ne connaissent ni Express ni les requêtes : ils reçoivent des valeurs, lèvent des AppError et s'appuient sur Prisma, Redis ou des clients externes. Les services propres à la blockchain (walletService, lotteryGateway, lotteryIndexer, keeper, file d'actions) sont dans backend/src/blockchain et décrits dans la partie Intégration blockchain du backend.

#sessionService

Signe et vérifie les jetons de session JWT et gère leur révocation. Le comportement vu de l'API est décrit dans Authentification.

revokeAllForUser est appelé à l'activation d'une 2FA, à la déconnexion de tous les appareils, à la réinitialisation ou au changement du mot de passe et à la confirmation d'une suppression RGPD. La marge d'une seconde garantit que le jeton émis juste après, dans la même requête, reste valable. Si un compte reste inactif plus de 30 jours, la clé expire, mais tous les jetons antérieurs ont expiré depuis longtemps.

#otpChallengeService

Gère les codes à 6 chiffres envoyés par email, le compteur d'échecs par compte et l'anti-rejeu des codes TOTP. Tout est stocké dans Redis.

La clé HMAC est dérivée de ENCRYPTION_KEY (HMAC(ENCRYPTION_KEY, "blocklucky:hmac")) dans backend/src/utils/crypto.util.ts : un dump Redis ne révèle pas les codes. Le compteur d'échecs est lu puis réécrit sans opération atomique : des tentatives parallèles peuvent en perdre quelques-unes.

#totpService

Implémentation interne de TOTP (RFC 6238) sans dépendance externe pour le calcul, la bibliothèque qrcode produisant seulement l'image.

Le secret est stocké chiffré en AES-256-GCM (encryptText) ; les codes de secours sont stockés hachés (SHA-256("backup:" + code normalisé)). Un ancien secret enregistré en clair est encore accepté à la lecture (isEncrypted).

#ledgerService

Seul point d'écriture des EtherPoints. Chaque opération modifie User.pointsBalance et ajoute une ligne PointTransaction dans une même transaction Prisma.

Les types autorisés sont TICKET_PURCHASE, REFERRAL, REWARD_CLAIM, SOCIAL_QUEST, GIFT_TICKET et ADMIN_BONUS ; la colonne actionType est une chaîne libre en base. Chaque opération incrémente la métrique business_events_total{event="points_credited_<type>"} ou points_debited_<type>.

La vérification du solde de debitPoints est faite avant la transaction : deux débits simultanés peuvent passer la vérification, mais la contrainte CHECK ("pointsBalance" >= 0) fait alors échouer le second en 409. La file ledger-queue qui devait sérialiser ces écritures n'est utilisée par aucun appelant (voir Files et workers).

#emailService

Rend un gabarit HTML et l'envoie par Nodemailer (backend/src/config/mailer.config.ts). Les modules n'appellent pas ce service directement : ils passent par enqueueEmail, qui met le message dans la file emails-queue ou l'envoie immédiatement si la file est indisponible.

Les gabarits sont dans backend/src/templates/emails/. Chaque {{VARIABLE}} est remplacée par sa valeur échappée pour HTML. Si le fichier est introuvable, le corps se réduit aux variables en JSON. Un quatrième argument facultatif, { replyTo }, ajoute une adresse de réponse au message. npm run compile copie le dossier dans dist/src/templates.

Comme l'échec SMTP ne lève pas d'erreur, un job de la file d'emails est considéré comme réussi même si le message n'est pas parti, et les 5 tentatives de BullMQ ne sont jamais utilisées. Les méthodes sendOtpEmail, sendSecurityAlertEmail, sendGdprDeletionEmail, sendRewardClaimEmail et sendWelcomeEmail existent mais ne sont appelées par aucun code. Le guide Ajouter un email décrit la création d'un gabarit.

#s3Service

Client @aws-sdk/client-s3 configuré par AWS_REGION, AWS_S3_ENDPOINT, AWS_ACCESS_KEY_ID et AWS_SECRET_ACCESS_KEY, en style chemin (forcePathStyle, compatible MinIO), 3 tentatives, délais de 3 secondes à la connexion et 10 secondes par requête.

Le seul appelant est l'export de rapports (GET /admin/reports/export). Aucun conteneur MinIO n'est défini dans docker-compose.yml : en local, l'envoi échoue et l'URL renvoyée ne pointe vers rien.

#blockchainService

Façade historique du mode simulé. En mode onchain, seules deux méthodes délèguent au vrai contrat ; les autres ne servent qu'en mode simulé.

Le service crée ses propres fournisseurs ethers vers RPC_URL et FALLBACK_RPC_URL (délai de 10 secondes), qu'il n'utilise pas : les appels réels passent par chainClient. Voir Mode onchain ou simulé.

#Utilitaires associés

Les choix cryptographiques sont justifiés dans Cryptographie et secrets.