Skip to content

Auth Service

Jump to bottom
rom98759 edited this page Jan 27, 2026 · 1 revision

Auth Service

Le service d'authentification gère l'ensemble des fonctionnalités liées à l'authentification des utilisateurs, incluant l'inscription, la connexion, l'authentification à deux facteurs (2FA/TOTP), et la gestion des tokens JWT.

📋 Table des matières

Architecture

Le service Auth suit une architecture en couches (layered architecture) :

Request → Routes → Controllers → Services → Database

Principe de responsabilité unique

  • Routes : Définition des endpoints et validation des inputs (schémas JSON)
  • Controllers : Gestion des requêtes/réponses HTTP, orchestration
  • Services : Logique métier (business logic)
  • Database : Accès aux données (SQLite via better-sqlite3)

Technologies utilisées

Technologie Usage Documentation
Fastify Framework web haute performance Fastify
TypeScript Typage statique TypeScript
better-sqlite3 Base de données embarquée npm
bcrypt Hashing de mots de passe npm
@fastify/jwt Génération et validation JWT GitHub
@fastify/cookie Gestion des cookies GitHub
@fastify/rate-limit Protection contre les abus GitHub
otplib TOTP (Time-based OTP) npm
qrcode Génération de QR codes pour 2FA npm

Configuration

Variables d'environnement

Fichier : srcs/.env.auth

# Environnement
NODE_ENV=production                    # development | test | production | staging

# Logging
LOG_ENABLED=true
LOG_LEVEL=info                         # debug | info | warn | error

# JWT Configuration - CRITIQUE SÉCURITÉ
JWT_SECRET=your-super-secret-key-here-min-32-chars

# Service Configuration
AUTH_SERVICE_PORT=3001
AUTH_SERVICE_NAME=auth-service
AUTH_DB_PATH=/data/auth.db            # Chemin vers la base SQLite

# Redis Configuration
REDIS_HOST=redis-broker
REDIS_PORT=6379
REDIS_PASSWORD=

# User Management Service
UM_SERVICE_NAME=user-service
UM_SERVICE_PORT=3002

# Admin User Configuration (utilisateur créé au démarrage)
ADMIN_USERNAME=admin
ADMIN_EMAIL=admin@transcendence.local
ADMIN_PASSWORD=Admin123!              # ⚠️ À CHANGER EN PRODUCTION

# Invite User Configuration (utilisateur invité)
INVITE_USERNAME=invite
INVITE_EMAIL=invite@transcendence.local
INVITE_PASSWORD=Invite123!            # ⚠️ À CHANGER EN PRODUCTION

# Application Configuration
APP_NAME=Transcendence                # Nom affiché dans l'app d'authentification 2FA

⚠️ CRITIQUE : Le JWT_SECRET doit être :

  • Au minimum 32 caractères (validation stricte au démarrage)
  • Généré aléatoirement : node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
  • Jamais committé dans Git
  • Différent entre dev et production
  • Le service refuse de démarrer si le secret est invalide ou trop court

Structure du projet

srcs/auth/
├── src/
│   ├── index.ts                    # Point d'entrée, configuration Fastify
│   ├── config/
│   │   ├── env.ts                  # Validation des variables d'environnement
│   │   └── logger.config.ts        # Configuration Pino logger
│   ├── controllers/
│   │   └── auth.controller.ts      # Handlers HTTP (login, register, 2FA, etc.)
│   ├── routes/
│   │   └── auth.routes.ts          # Définition des routes et rate limiting
│   ├── services/
│   │   ├── auth.service.ts         # Logique métier authentification
│   │   ├── jwt.service.ts          # Génération et validation JWT
│   │   ├── totp.service.ts         # Service TOTP/2FA
│   │   ├── database.ts             # Accès base de données
│   │   └── external/
│   │       └── um.service.ts       # Appels au service Users
│   ├── types/
│   │   ├── dto.ts                  # Data Transfer Objects
│   │   ├── errors.ts               # Classes d'erreurs personnalisées
│   │   ├── logger.ts               # Types pour le logger
│   │   └── models.ts               # Modèles de données
│   └── utils/
│       ├── constants.ts            # Constantes (codes d'erreur, config)
│       ├── error-catalog.ts        # Catalogue d'erreurs
│       ├── init-users.ts           # Initialisation utilisateurs admin
│       └── validation.ts           # Schémas de validation Zod
├── Dockerfile                      # Image de production
├── Dockerfile.dev                  # Image de développement
├── package.json
└── tsconfig.json

Fonctionnalités

1. Inscription (Register)

  • Validation des données (email, username, password)
  • Vérification de l'unicité (email et username)
  • Hashing du mot de passe avec bcrypt (10 rounds)
  • Création de l'utilisateur dans la base
  • Génération d'un JWT
  • Retour du token dans un cookie HTTP-only

2. Connexion (Login)

  • Vérification des credentials (username/email + password)
  • Support de l'authentification 2FA
    • Si 2FA activé : retour d'un token temporaire
    • Si 2FA désactivé : connexion directe
  • Génération du JWT
  • Rate limiting strict (5 tentatives / minute)

3. Déconnexion (Logout)

  • Invalidation du cookie token
  • Retour d'un cookie expiré

4. Authentification à deux facteurs (2FA)

Configuration 2FA

  • Génération d'un secret TOTP unique
  • Création d'une URL otpauth:// compatible Google Authenticator
  • Génération d'un QR code (base64)
  • Stockage temporaire du secret (2 minutes)
  • Cookie de session setup

Vérification du setup

  • Validation du code TOTP à 6 chiffres
  • Activation permanente du 2FA dans le profil
  • Stockage du secret TOTP

Login avec 2FA

  • Après login initial : token temporaire (2 minutes)
  • Validation du code TOTP
  • Maximum 3 tentatives
  • Génération du JWT final après validation

Désactivation 2FA

  • Par l'utilisateur (nécessite mot de passe)
  • Par un admin (endpoint dédié)

5. Vérification de token (Verify)

  • Endpoint pour vérifier la validité d'un JWT
  • Utilisé par les autres services

6. Administration

  • Liste de tous les utilisateurs
  • Création d'utilisateurs
  • Mise à jour d'utilisateurs
  • Suppression d'utilisateurs
  • Désactivation forcée du 2FA

API Endpoints

Important

Tous les endpoints sont préfixés par /api/auth

Exemple complet : https://URL:PORT/api/auth/login

Endpoints publics (non protégés)

Méthode Route Description Rate Limit Body
GET / Health check basique - -
GET /health Health check détaillé - -
POST /register Inscription d'un nouvel utilisateur 5/5min (dev: 100) { username, email, password }
POST /login Connexion 5/5min (dev: 100) { username ou email, password }

Détails /register:

  • Validation stricte avec Zod (username 4-20 chars alphanumériques + _, email valide, password 8+ chars avec maj, min, chiffre et caractère spécial !@#$%^&*)
  • Vérifie l'unicité du username et de l'email
  • Hash du password avec bcrypt (10 rounds)
  • Crée le profil utilisateur via le service UM (User Management)
  • Retourne les infos utilisateur (pas de token automatique - nécessite login)
  • Codes de retour:
    • 201 CREATED : Utilisateur créé
    • 400 BAD_REQUEST : Validation échouée
    • 409 CONFLICT : Username ou email déjà pris
    • 500 INTERNAL_SERVER_ERROR : Erreur serveur

Détails /login:

  • Accepte username OU email + password
  • Si 2FA activé : retourne require2FA: true + cookie temporaire 2fa_login_token (2 min)
  • Si 2FA désactivé : retourne JWT dans cookie token (1h)
  • Codes de retour:
    • 200 OK : Login réussi (avec ou sans 2FA)
    • 400 BAD_REQUEST : Validation échouée
    • 401 UNAUTHORIZED : Credentials invalides
    • 500 INTERNAL_SERVER_ERROR : Erreur serveur

Endpoints protégés (JWT requis)

Ces endpoints nécessitent un token JWT valide dans le cookie token OU le header Authorization: Bearer <token>. Le JWT est validé et les headers x-user-id et x-user-name sont injectés par la Gateway.

Méthode Route Description Headers injectés
POST /logout Déconnexion (efface le cookie) x-user-name
GET /me Récupérer infos utilisateur connecté x-user-id, x-user-name
POST /heartbeat Met à jour le statut "en ligne" dans Redis (TTL: 30s) x-user-id

Détails /me:

  • Retourne : { id, username, email, role, is2FAEnabled }
  • Note: Endpoint marqué "DEV ONLY" - à supprimer en production

Détails /heartbeat:

  • Rate limit: 10/10s
  • Utilisé par le frontend pour maintenir le statut "en ligne"
  • Stocke un heartbeat dans Redis avec TTL de 30 secondes
  • Si pas de heartbeat pendant 30s, l'utilisateur est considéré offline

Endpoints 2FA

Méthode Route Description Rate Limit Cookies requis
POST /2fa/setup Démarrer la configuration 2FA (génère QR code) 5/5min (dev: 100) token
POST /2fa/setup/verify Valider le code et activer la 2FA 5/5min (dev: 100) 2fa_setup_token
POST /2fa/verify Valider le code lors du login 5/5min (dev: 100) 2fa_login_token
POST /2fa/disable Désactiver la 2FA - token

Flow complet 2FA Setup:

  1. POST /2fa/setup (JWT requis)

    • Vérifie que 2FA n'est pas déjà activée
    • Génère un secret TOTP unique
    • Crée une URL otpauth://totp/Transcendence:username?secret=...
    • Génère un QR code en base64
    • Stocke le secret temporairement (2 min) avec un token de session
    • Retourne : { qrCode: "data:image/png;base64,...", expiresIn: 120 }
    • Cookie 2fa_setup_token créé (secure, httpOnly, 2 min)

  2. POST /2fa/setup/verify (cookie 2fa_setup_token requis)

    • Body: { code: "123456" } (6 chiffres)
    • Valide le code TOTP avec le secret temporaire
    • Max 3 tentatives, sinon doit recommencer le setup
    • Si valide : active la 2FA définitivement (stocke secret dans DB)
    • Génère un nouveau JWT et retourne cookie token
    • Supprime le cookie 2fa_setup_token

Flow complet 2FA Login:

  1. POST /login → retourne require2FA: true + cookie 2fa_login_token (2 min)

  2. POST /2fa/verify (cookie 2fa_login_token requis)

    • Body: { code: "123456" } (6 chiffres)
    • Valide le code TOTP avec le secret permanent
    • Max 3 tentatives, sinon doit se reconnecter
    • Si valide : génère JWT final et retourne cookie token
    • Supprime le cookie 2fa_login_token

Détails /2fa/disable:

  • Nécessite JWT valide
  • Vérifie que 2FA est activée
  • Supprime le secret TOTP de la DB
  • Désactive is_2fa_enabled dans le profil utilisateur

Endpoints admin (rôle ADMIN requis)

Tous ces endpoints nécessitent un JWT valide + rôle ADMIN. La vérification est faite via le pré-handler verifyAdminRole qui lit les headers x-user-id et x-user-name.

Méthode Route Description Rate Limit Body
GET /admin/users Liste tous les utilisateurs 50/min -
PUT /admin/users/:id Modifier un utilisateur 20/min { username, email, role }
DELETE /admin/users/:id Supprimer un utilisateur 10/min -
POST /admin/users/:id/disable-2fa Forcer désactivation 2FA 10/min -

Détails /admin/users (GET):

  • Retourne tous les utilisateurs avec :
    • Infos de base : id, username, email, role
    • État 2FA : is2FAEnabled
    • Statut en ligne : online (via Redis bulk check)
  • Response: { users: [{ id, username, email, role, is2FAEnabled, online }, ...] }

Détails /admin/users/:id (PUT):

  • Permet de modifier username, email et role
  • Vérifie l'unicité du username et de l'email
  • Role doit être user ou admin
  • Codes de retour:
    • 200 OK : Utilisateur modifié
    • 400 BAD_REQUEST : Données invalides
    • 403 FORBIDDEN : Non admin
    • 404 NOT_FOUND : Utilisateur inexistant
    • 409 CONFLICT : Username ou email déjà utilisé

Détails /admin/users/:id (DELETE):

  • Empêche l'auto-suppression (admin ne peut pas se supprimer)
  • Supprime l'utilisateur de la DB Auth + appelle le service UM pour cleanup
  • Codes de retour:
    • 200 OK : Utilisateur supprimé
    • 400 BAD_REQUEST : Tentative d'auto-suppression
    • 403 FORBIDDEN : Non admin
    • 404 NOT_FOUND : Utilisateur inexistant

Détails /admin/users/:id/disable-2fa (POST):

  • Désactive la 2FA d'un utilisateur (pour déblocage)
  • Vérifie que la 2FA est activée avant de la désactiver
  • Codes de retour:
    • 200 OK : 2FA désactivée
    • 400 BAD_REQUEST : 2FA déjà désactivée
    • 403 FORBIDDEN : Non admin
    • 404 NOT_FOUND : Utilisateur inexistant

Endpoint de vérification de statut

Méthode Route Description Rate Limit Params
GET /is-online/:name Vérifie si un utilisateur est en ligne 200/min (dev: 1000) name (username)

Détails /is-online/:name:

  • Retourne : { username: "...", isOnline: true/false }
  • Vérifie dans Redis si un heartbeat existe (< 30s)
  • Codes de retour:
    • 200 OK : Status retourné
    • 400 BAD_REQUEST : Username manquant
    • 404 NOT_FOUND : Utilisateur inexistant

Authentification JWT

Structure du token

Le JWT contient les informations suivantes dans le payload :

{
  "sub": 123,              // User ID (subject)
  "username": "alice",     // Nom d'utilisateur
  "role": "user",          // Rôle (user | admin)
  "iat": 1640000000,       // Issued at (timestamp)
  "exp": 1640003600        // Expiration (timestamp)
}

Génération du JWT

Cycle de vie

  1. Génération : Lors du login réussi ou après validation 2FA
  2. Stockage : Cookie HTTP-only nommé token
  3. Validation : Par la Gateway avant chaque requête protégée
  4. Headers injectés : x-user-id et x-user-name ajoutés par la Gateway après validation
  5. Expiration : 1 heure (défini dans AUTH_CONFIG.JWT_EXPIRATION = '1h')

Configuration du cookie

{
  httpOnly: true,      // Pas accessible en JavaScript (protection XSS)
  secure: true,        // HTTPS uniquement (production, ou si FORCE_SECURE_COOKIE=true)
  sameSite: 'strict',  // Protection CSRF (note: pas 'lax')
  path: '/',           // Disponible sur toutes les routes
  maxAge: 3600         // 1 heure (sync avec JWT expiration)
}

Note: En développement, secure: false est autorisé si NODE_ENV=development ET FORCE_SECURE_COOKIE n'est pas défini.

Validation du token

La Gateway valide les JWT pour des raisons de performance :

// La Gateway :
// 1. Extrait le token du cookie 'token' ou du header 'Authorization: Bearer <token>'
// 2. Vérifie la signature JWT avec JWT_SECRET (identique côté Auth et Gateway)
// 3. Décode le payload
// 4. Injecte les headers x-user-id, x-user-name, x-user-role
// 5. Proxyfy la requête vers le service cible

Sécurité JWT

✅ Bonnes pratiques implémentées :

  • Secret d'au moins 32 caractères (validation stricte au démarrage avec envalid)
  • Algorithme HS256 (HMAC + SHA256) via @fastify/jwt
  • Validation stricte du format et de la signature
  • Vérification de l'expiration automatique par @fastify/jwt
  • Cookie HTTP-only (protection XSS)
  • Cookie SameSite=strict (protection CSRF)
  • Cookie Secure en production (HTTPS only)
  • Validation locale par la Gateway

⚠️ À implémenter (roadmap) :

  • Refresh tokens : pour prolonger la session sans re-login complet
  • Révocation de tokens : blacklist Redis pour logout forcé/invalidation immédiate
  • Rotation du secret JWT : permettre le changement du secret sans casser toutes les sessions
  • Token version/jti : invalider tous les tokens d'un utilisateur en une fois (ex: après changement de password)

2FA / TOTP

Fonctionnement du TOTP

TOTP (Time-based One-Time Password) génère des codes à 6 chiffres basés sur :

  • Un secret partagé (stocké dans la DB Auth et dans l'app authenticator de l'utilisateur)
  • Le temps actuel (fenêtres de 30 secondes)
Code = HMAC-SHA1(secret, floor(timestamp / 30))

Paramètres TOTP:

  • Algorithme : SHA1 (standard TOTP)
  • Période : 30 secondes (défini dans AUTH_CONFIG.TOTP_STEP = 30)
  • Digits : 6 chiffres (défini dans AUTH_CONFIG.TOTP_DIGITS = 6)
  • Window : ±1 période (±30s, défini dans AUTH_CONFIG.TOTP_WINDOW = 1)
  • Issuer : "Transcendence" (défini dans AUTH_CONFIG.TOTP_ISSUER via APP_NAME)

Configuration TOTP

// utils/constants.ts
TOTP_WINDOW: 1,          // ±30 secondes de tolérance
TOTP_STEP: 30,           // Période de rotation (standard)
TOTP_DIGITS: 6,          // Code à 6 chiffres
TOTP_ISSUER: 'Transcendence',
TOTP_SETUP_EXPIRATION_SECONDS: 120,  // Expiration du secret temporaire

Flow complet 2FA

1. Setup (activation initiale)

sequenceDiagram
    participant User
    participant Frontend
    participant Auth Service
    participant SQLite DB
    participant Authenticator App

    User->>Frontend: Clique "Activer 2FA"
    Frontend->>Auth Service: POST /2fa/setup (JWT token)
    Auth Service->>Auth Service: Vérifie que 2FA pas déjà activée
    Auth Service->>Auth Service: Génère secret TOTP aléatoire
    Auth Service->>Auth Service: Crée URL otpauth://totp/...
    Auth Service->>Auth Service: Génère QR code (base64)
    Auth Service->>SQLite DB: INSERT INTO totp_setup_secrets (token, user_id, secret, expires_at)
    Auth Service-->>Frontend: Cookie 2fa_setup_token (2 min) + QR code
    Frontend->>User: Affiche QR code
    User->>Authenticator App: Scanne QR code
    Authenticator App->>Authenticator App: Stocke secret localement
    Authenticator App->>User: Affiche code 6 chiffres
    User->>Frontend: Entre code
    Frontend->>Auth Service: POST /2fa/setup/verify + code
    Auth Service->>SQLite DB: Récupère secret temporaire via token
    Auth Service->>Auth Service: Valide code TOTP (max 3 tentatives)
    Auth Service->>SQLite DB: UPDATE users SET is_2fa_enabled=1, totp_secret=...
    Auth Service->>SQLite DB: DELETE FROM totp_setup_secrets
    Auth Service->>Auth Service: Génère nouveau JWT
    Auth Service-->>Frontend: Cookie token (1h)
    Frontend->>User: "2FA activée ✓"
Loading

2. Login avec 2FA

sequenceDiagram
    participant User
    participant Frontend
    participant Auth Service
    participant SQLite DB
    participant Authenticator App

    User->>Frontend: Entre username + password
    Frontend->>Auth Service: POST /login
    Auth Service->>SQLite DB: Vérifie credentials
    Auth Service->>SQLite DB: Vérifie si is_2fa_enabled=1
    Auth Service->>Auth Service: Génère loginToken temporaire
    Auth Service->>SQLite DB: INSERT INTO login_tokens
    Auth Service-->>Frontend: Cookie 2fa_login_token (2 min) + require2FA: true
    Frontend->>User: Demande code 2FA
    User->>Authenticator App: Ouvre app
    Authenticator App->>User: Affiche code 6 chiffres
    User->>Frontend: Entre code
    Frontend->>Auth Service: POST /2fa/verify + code
    Auth Service->>SQLite DB: Récupère user_id via loginToken
    Auth Service->>SQLite DB: Récupère totp_secret de l'utilisateur
    Auth Service->>Auth Service: Valide code TOTP (max 3 tentatives)
    Auth Service->>SQLite DB: DELETE FROM login_tokens
    Auth Service->>Auth Service: Génère JWT final
    Auth Service-->>Frontend: Cookie token (1h)
    Frontend->>User: Connecté ✓
Loading

Tables de base de données

Table users (extraits colonnes 2FA)

CREATE TABLE users (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  username TEXT UNIQUE NOT NULL,
  email TEXT UNIQUE NOT NULL,
  password_hash TEXT NOT NULL,
  role TEXT DEFAULT 'user',  -- 'user' | 'admin'
  is_2fa_enabled INTEGER DEFAULT 0,  -- Boolean (0 ou 1)
  totp_secret TEXT,                   -- Secret TOTP chiffré (ou NULL si 2FA désactivée)
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

Table totp_setup_secrets

Stockage temporaire pendant la configuration (2 minutes) :

CREATE TABLE totp_setup_secrets (
  token TEXT PRIMARY KEY,                       -- Token UUID aléatoire
  user_id INTEGER NOT NULL,
  secret TEXT NOT NULL,                         -- Secret TOTP temporaire
  expires_at DATETIME NOT NULL,                 -- Timestamp d'expiration (now + 120s)
  attempts INTEGER DEFAULT 0,                   -- Compteur de tentatives (max 3)
  FOREIGN KEY(user_id) REFERENCES users(id) ON DELETE CASCADE
);

Nettoyage: Supprimé automatiquement après validation réussie ou expiration.

Table login_tokens

Tokens temporaires pour le login 2FA (2 minutes) :

CREATE TABLE login_tokens (
  token TEXT PRIMARY KEY,                       -- Token UUID aléatoire
  user_id INTEGER NOT NULL,
  expires_at DATETIME NOT NULL,                 -- Timestamp d'expiration (now + 120s)
  FOREIGN KEY(user_id) REFERENCES users(id) ON DELETE CASCADE
);

Table login_token_attempts

Compteur de tentatives (max 3) pour les login tokens :

CREATE TABLE login_token_attempts (
  token TEXT PRIMARY KEY,                       -- Référence au login_token
  attempts INTEGER DEFAULT 0,                   -- Nombre de tentatives échouées (max 3)
  FOREIGN KEY(token) REFERENCES login_tokens(token) ON DELETE CASCADE
);

Logique de sécurité:

  • Max 3 tentatives de code TOTP
  • Au-delà : suppression du login_token → utilisateur doit se reconnecter avec username/password

Nettoyage automatique

Le service effectue un nettoyage périodique des sessions expirées :

// index.ts
setInterval(() => {
  totpService.cleanupExpiredSessions();
  authService.cleanupExpiredTokens();
}, AUTH_CONFIG.CLEANUP_INTERVAL_MS);  // 5 minutes

Éléments nettoyés:

  • totp_setup_secrets expirés (> 2 min)
  • login_tokens expirés (> 2 min)
  • Entrées orphelines dans login_token_attempts
  • Au démarrage du service
  • Toutes les 5 minutes (maintenance automatique)

Sécurité

Mesures de protection implémentées

1. Rate Limiting

Limites adaptées selon l'environnement (dev/test vs production) :

Endpoint Limite Prod Limite Dev/Test Fenêtre
Global 1000 req 10000 req 1 minute
/register 5 req 100 req 5 minutes
/login 5 req 100 req 5 minutes
/2fa/setup 5 req 100 req 5 minutes
/2fa/setup/verify 5 req 100 req 5 minutes
/2fa/verify 5 req 100 req 5 minutes
/heartbeat 10 req 10 req 10 secondes
/is-online/:name 200 req 1000 req 1 minute
/admin/users (GET) 50 req 50 req 1 minute
/admin/users/:id (PUT) 20 req 20 req 1 minute
/admin/users/:id (DELETE) 10 req 10 req 1 minute
/admin/users/:id/disable-2fa 10 req 10 req 1 minute

Configuration:

// utils/constants.ts
const isTestOrDev = ['test', 'development'].includes(authenv.NODE_ENV);

RATE_LIMIT: {
  LOGIN: {
    max: isTestOrDev ? 100 : 5,
    timeWindow: '5 minutes',
  },
  // ...
}

Implémentation: Plugin @fastify/rate-limit configuré par route.

2. Hashing des mots de passe

  • Algorithme : bcrypt (via bcrypt npm package)
  • Rounds : 10 (défini dans AUTH_CONFIG.BCRYPT_ROUNDS = 10)
  • Jamais de stockage en clair
  • Salt : généré automatiquement par bcrypt (intégré au hash)
import bcrypt from 'bcrypt';

// Hash lors de l'inscription
const hashedPassword = await bcrypt.hash(password, AUTH_CONFIG.BCRYPT_ROUNDS);

// Vérification lors du login
const isValid = await bcrypt.compare(password, user.password_hash);

3. Validation des entrées

Utilisation de Zod pour valider tous les inputs utilisateur :

// utils/validation.ts
const registerSchema = z.object({
  username: z.string()
    .min(4, 'Username must be at least 4 characters')
    .max(20, 'Username must be at most 20 characters')
    .regex(/^[a-zA-Z0-9_]+$/, 'Username must contain only letters, numbers and underscores')
    .refine(val => !RESERVED_USERNAMES.includes(val.toLowerCase()),
            { message: 'This username is reserved' }),

  email: z.string()
    .email('Invalid email format')
    .max(100, 'Email too long'),

  password: z.string()
    .min(8, 'Password must be at least 8 characters')
    .max(100, 'Password too long')
    .regex(/^(?=.*[a-z])/, 'Must contain lowercase letter')
    .regex(/^(?=.*[A-Z])/, 'Must contain uppercase letter')
    .regex(/^(?=.*\d)/, 'Must contain a number')
    .regex(/^(?=.*[!@#$%^&*])/, 'Must contain special character (!@#$%^&*)')
});

Usernames réservés:

// utils/constants.ts
const RESERVED_USERNAMES = [
  'admin', 'root', 'system', 'administrator',
  'superuser', 'guest', 'support', 'service', 'daemon'
];

4. Protection des données sensibles

Champs sensibles jamais loggés en clair:

// utils/constants.ts
const SENSITIVE_FIELDS = [
  'password', 'token', 'secret', 'totp_secret',
  'jwt', 'authorization', 'cookie', 'loginToken',
  '2fa_login_token', '2fa_setup_token',
  'access_token', 'refresh_token',
];

const REDACT_PATHS = [
  'req.headers.authorization',
  'req.headers.cookie',
  ...SENSITIVE_FIELDS.map(field => `*.${field}`),
];

Configuration Pino logger:

// config/logger.config.ts
import pino from 'pino';

const logger = pino({
  redact: {
    paths: REDACT_PATHS,
    censor: '[REDACTED]',
  },
});

5. Cookies sécurisés

Configuration stricte des cookies JWT:

  • httpOnly: true → Pas accessible en JavaScript (protection XSS)
  • secure: true → HTTPS uniquement en production
  • sameSite: 'strict' → Protection CSRF
  • path: '/' → Disponible sur toutes les routes
  • Pas de cookie persistent → Expiration synchronisée avec JWT (1h)

6. Headers de sécurité

Headers automatiquement ajoutés par Fastify (via plugins ou configuration) :

  • X-Content-Type-Options: nosniff → Empêche le MIME sniffing
  • X-Frame-Options: DENY → Empêche l'iframe (protection clickjacking)
  • X-XSS-Protection: 1; mode=block → Active la protection XSS du navigateur

7. Protection 2FA

  • Max 3 tentatives de code TOTP (setup et login)
  • Expiration courte des tokens temporaires (2 minutes)
  • Nettoyage automatique des sessions expirées (toutes les 5 minutes)
  • Window TOTP de ±30s pour compenser le décalage horaire

8. Protection Admin

  • Vérification du rôle via pré-handler verifyAdminRole
  • Empêche l'auto-suppression (admin ne peut pas se supprimer)
  • Logs détaillés de toutes les actions admin (avec user_id et username)

9. Sécurité de la base de données

  • Requêtes préparées : utilisation de better-sqlite3 avec placeholders (?)
  • Transactions : pour les opérations critiques (register + création profil UM)
  • Contraintes DB : UNIQUE sur username et email, FOREIGN KEY avec ON DELETE CASCADE
  • Isolation : base SQLite locale, pas d'accès direct depuis l'extérieur

Système de statut en ligne (Redis)

Le service Auth gère le statut "en ligne" des utilisateurs via Redis.

Architecture

Frontend → POST /heartbeat (toutes les 10-20s)
         → Auth Service → Redis SET user:{userId}:online EX 30

Autre service → GET /is-online/:name
              → Auth Service → Redis GET user:{userId}:online

Heartbeat

Endpoint: POST /heartbeat

// services/online.service.ts
async function recordHeartbeat(userId: number): Promise<void> {
  const key = `user:${userId}:online`;
  await redis.setex(key, 30, Date.now().toString());
  // TTL: 30 secondes
}

Logique:

  • Le frontend envoie un heartbeat toutes les 10-20 secondes
  • Redis stocke une clé avec TTL de 30 secondes
  • Si pas de heartbeat pendant 30s → clé expirée → utilisateur offline

Rate limit: 10 requêtes / 10 secondes (pour éviter le spam)

Vérification du statut

Endpoint: GET /is-online/:name

async function isUserOnline(userId: number): Promise<boolean> {
  const key = `user:${userId}:online`;
  const result = await redis.get(key);
  return result !== null;
}

Bulk check (pour /admin/users) :

async function getBulkOnlineStatus(userIds: number[]): Promise<Map<number, boolean>> {
  const pipeline = redis.pipeline();
  userIds.forEach(id => pipeline.get(`user:${id}:online`));

  const results = await pipeline.exec();
  const statusMap = new Map<number, boolean>();

  userIds.forEach((id, index) => {
    statusMap.set(id, results[index][1] !== null);
  });

  return statusMap;
}

Nettoyage

Redis gère automatiquement l'expiration des clés (TTL 30s).

Un nettoyage supplémentaire est effectué toutes les 60 secondes :

// index.ts
setInterval(() => {
  onlineService.cleanupStaleHeartbeats();
}, AUTH_CONFIG.ONLINE_STATUS_CLEANUP_INTERVAL_MS);  // 60 secondes

Configuration Redis

// config/env.ts
REDIS_HOST: str({ default: 'redis-broker' }),
REDIS_PORT: port({ default: 6379 }),
REDIS_PASSWORD: str({ default: '' }),

Connexion:

// services/online.service.ts
import Redis from 'ioredis';

const redis = new Redis({
  host: authenv.REDIS_HOST,
  port: authenv.REDIS_PORT,
  password: authenv.REDIS_PASSWORD,
  lazyConnect: true,
  retryStrategy: (times) => Math.min(times * 50, 2000),
});

Base de données (SQLite)

Configuration

  • Moteur : SQLite via better-sqlite3
  • Chemin : /data/auth.db (configurable via AUTH_DB_PATH)
  • Mode : WAL (Write-Ahead Logging) pour de meilleures performances
  • Contraintes : Foreign keys activées
// services/database.ts
import Database from 'better-sqlite3';

const db = new Database(authenv.AUTH_DB_PATH);
db.pragma('journal_mode = WAL');
db.pragma('foreign_keys = ON');

Schéma complet

Table users 

CREATE TABLE users (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  username TEXT UNIQUE NOT NULL,
  email TEXT UNIQUE NOT NULL,
  password_hash TEXT NOT NULL,
  role TEXT DEFAULT 'user' CHECK(role IN ('user', 'admin')),
  is_2fa_enabled INTEGER DEFAULT 0 CHECK(is_2fa_enabled IN (0, 1)),
  totp_secret TEXT,
  created_at TEXT DEFAULT (datetime('now')),
  updated_at TEXT DEFAULT (datetime('now'))
);

CREATE INDEX idx_users_username ON users(username);
CREATE INDEX idx_users_email ON users(email);
CREATE INDEX idx_users_role ON users(role);

Colonnes:

  • id : ID unique auto-incrémenté
  • username : Nom d'utilisateur unique (4-20 chars)
  • email : Email unique (validé côté app)
  • password_hash : Hash bcrypt du mot de passe (60 chars)
  • role : Rôle ('user' | 'admin')
  • is_2fa_enabled : Boolean (0 ou 1)
  • totp_secret : Secret TOTP chiffré (NULL si 2FA désactivée)
  • created_at : Date de création (ISO 8601)
  • updated_at : Date de dernière modification (ISO 8601)

Table totp_setup_secrets 

CREATE TABLE totp_setup_secrets (
  token TEXT PRIMARY KEY,
  user_id INTEGER NOT NULL,
  secret TEXT NOT NULL,
  expires_at TEXT NOT NULL,
  attempts INTEGER DEFAULT 0,
  FOREIGN KEY(user_id) REFERENCES users(id) ON DELETE CASCADE
);

CREATE INDEX idx_totp_setup_expires ON totp_setup_secrets(expires_at);
CREATE INDEX idx_totp_setup_user ON totp_setup_secrets(user_id);

Usage: Stockage temporaire du secret TOTP pendant la configuration (2 min).

Table login_tokens 

CREATE TABLE login_tokens (
  token TEXT PRIMARY KEY,
  user_id INTEGER NOT NULL,
  expires_at TEXT NOT NULL,
  FOREIGN KEY(user_id) REFERENCES users(id) ON DELETE CASCADE
);

CREATE INDEX idx_login_tokens_expires ON login_tokens(expires_at);
CREATE INDEX idx_login_tokens_user ON login_tokens(user_id);

Usage: Tokens temporaires pour le login 2FA (2 min).

Table login_token_attempts 

CREATE TABLE login_token_attempts (
  token TEXT PRIMARY KEY,
  attempts INTEGER DEFAULT 0,
  FOREIGN KEY(token) REFERENCES login_tokens(token) ON DELETE CASCADE
);

Usage: Compteur de tentatives de validation TOTP (max 3).

Requêtes préparées

Toutes les requêtes utilisent des prepared statements pour éviter les injections SQL :

// ✅ Bon (prepared statement)
const stmt = db.prepare('SELECT * FROM users WHERE username = ?');
const user = stmt.get(username);

// ❌ Mauvais (injection SQL possible)
const user = db.prepare(`SELECT * FROM users WHERE username = '${username}'`).get();

Transactions

Les opérations critiques utilisent des transactions :

// services/auth.service.ts
function createUser(data: CreateUserInput): number {
  const transaction = db.transaction(() => {
    // 1. Créer utilisateur dans Auth DB
    const result = db.prepare(`
      INSERT INTO users (username, email, password_hash, role)
      VALUES (?, ?, ?, ?)
    `).run(data.username, data.email, data.password_hash, 'user');

    const userId = result.lastInsertRowid as number;

    // 2. Créer profil dans User Management Service
    await umService.createProfile(userId, data.username, data.email);

    return userId;
  });

  return transaction();
}

Initialisation

Au démarrage, le service :

  1. Crée les tables si elles n'existent pas
  2. Crée un utilisateur admin par défaut (si pas déjà existant)
  3. Crée un utilisateur invite par défaut (si pas déjà existant)
// utils/init-users.ts
export function initializeDefaultUsers() {
  // Admin user
  if (!authService.findByUsername(authenv.ADMIN_USERNAME)) {
    authService.createUser({
      username: authenv.ADMIN_USERNAME,
      email: authenv.ADMIN_EMAIL,
      password: authenv.ADMIN_PASSWORD,
      role: UserRole.ADMIN,
    });
  }

  // Invite user
  if (!authService.findByUsername(authenv.INVITE_USERNAME)) {
    authService.createUser({
      username: authenv.INVITE_USERNAME,
      email: authenv.INVITE_EMAIL,
      password: authenv.INVITE_PASSWORD,
      role: UserRole.USER,
    });
  }
}

Backup et persistance

  • Volume Docker : /data monté sur l'hôte (data/database/auth.db)
  • Mode WAL : fichiers -shm et -wal créés automatiquement
  • Pas de migration automatique : schéma stable, migrations manuelles si nécessaire

Tests et validation

Scripts de test

Le projet fournit des scripts de test bash :

# Test du service Auth complet
./test-auth.sh

# Test cross-service (Auth + Users)
./test-auth-cross.sh

Tests manuels avec curl

Register

curl -X POST http://localhost:3001/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "testuser",
    "email": "test@example.com",
    "password": "Test123!@#"
  }'

Login

curl -X POST http://localhost:3001/login \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{
    "username": "testuser",
    "password": "Test123!@#"
  }'

Heartbeat

curl -X POST http://localhost:3001/heartbeat \
  -b cookies.txt

Admin - List users

curl -X GET http://localhost:3001/admin/users \
  -b cookies.txt

Service Gateway

  • Vérifier le statut en ligne : GET /is-online/:name

Headers injectés par la Gateway après validation :

  • x-user-id : ID de l'utilisateur
  • x-user-name : Username de l'utilisateur
  • x-user-role : Rôle de l'utilisateur

Service Redis

Le service Auth utilise Redis pour :

  1. Heartbeats : Statut en ligne des utilisateurs
  2. Futures features : Token blacklist, session store, rate limiting distribué

Roadmap et améliorations

Priorité haute

  • Refresh tokens : Prolonger la session sans re-login
  • Token blacklist : Invalider les JWT (logout forcé)
  • Account recovery : Reset password par email
  • Email verification : Valider l'email lors de l'inscription
  • Tests unitaires : Vitest pour chaque service/controller

Priorité moyenne

  • Rotation JWT secret : Permettre le changement du secret sans casser les sessions
  • Session management : Vue admin des sessions actives
  • IP whitelisting : Restreindre les connexions admin par IP
  • Audit logs : Logs persistés pour compliance
  • CAPTCHA : Protection brute force avancée

Priorité basse

  • OAuth providers : Login avec Google, GitHub, 42
  • Multi-device 2FA : Backup codes, SMS
  • Rate limiting distribué : Via Redis pour scale horizontale

Références

Documentation interne

Documentation externe

Contributeurs

Rom9

Dernière mise à jour: 27 janvier 2026

Home

🏗️ Architecture

🌐 Web Technologies

Backend

Frontend

🔧 Core Technologies

🔐 Security

⛓️ Blockchain

🛠️ Dev Tools & Quality

📝 Page model

Clone this wiki locally