🛠️ PLAN D'IMPLÉMENTATION¶

PD-25 — Authentification SRP-6a (Phase 2 : preuve, clé de session, token)

📌 EPIC ➡️ PD-189 — CRYPTO

📌 Artefact produit ➡️ PD-25-plan.md

1. Découpage en composants¶

1.1 Composants existants (PD-24)¶

1.2 Composants à enrichir (PD-25)¶

1.3 Nouveaux composants¶

2. Flux techniques¶

2.1 Diagramme de séquence Phase 2¶

┌────────┐                           ┌────────┐                    ┌───────┐
│ Client │                           │ Serveur│                    │ Redis │
└───┬────┘                           └───┬────┘                    └───┬───┘
    │                                    │                             │
    │  POST /auth/login/verify           │                             │
    │  { email, M1 }                     │                             │
    │───────────────────────────────────►│                             │
    │                                    │                             │
    │                                    │  GET srp:session:{email}    │
    │                                    │────────────────────────────►│
    │                                    │                             │
    │                                    │  { A, b, B, salt, verifier }│
    │                                    │◄────────────────────────────│
    │                                    │                             │
    │                  ┌─────────────────┴─────────────────┐           │
    │                  │  ══ PHASE VÉRIFICATION ══         │           │
    │                  │  (K est calculée mais NON établie)│           │
    │                  │                                   │           │
    │                  │ 1. Calculer u = SHA3-256(A || B)  │           │
    │                  │ 2. Calculer S = (A * v^u)^b mod N │           │
    │                  │ 3. Calculer K' = SHA3-256(S)      │           │
    │                  │    ⚠️  K' est une valeur candidate │           │
    │                  │ 4. Calculer M1' = SHA3-256(A||B||K')          │
    │                  │ 5. Vérifier M1' === M1            │           │
    │                  │    ❌ Si échec → K' est REJETÉE   │           │
    │                  └─────────────────┬─────────────────┘           │
    │                                    │                             │
    │                                    │  [Si M1 invalide → 401]     │
    │                                    │  K' n'est jamais établie    │
    │                                    │                             │
    │                  ┌─────────────────┴─────────────────┐           │
    │                  │  ══ PHASE POST-VÉRIFICATION ══    │           │
    │                  │  (K est maintenant ÉTABLIE)       │           │
    │                  │                                   │           │
    │                  │ 6. K := K' (clé de session valide)│           │
    │                  │ 7. Calculer M2 = SHA3-256(A||M1||K)│          │
    │                  │ 8. Générer JWT (email, sub)       │           │
    │                  │ 9. Émettre événement audit SUCCESS│           │
    │                  └─────────────────┬─────────────────┘           │
    │                                    │                             │
    │                                    │  DEL srp:session:{email}    │
    │                                    │────────────────────────────►│
    │                                    │                             │
    │  { accessToken, M2 }               │                             │
    │◄───────────────────────────────────│                             │
    │                                    │                             │
    │  [Client vérifie M2]               │                             │
    │                                    │                             │

Note importante (INV-3) : Le protocole SRP-6a nécessite de calculer K' pour vérifier M1 (car M1 = SHA3-256(A||B||K)). Cependant, K' reste une valeur candidate jusqu'à ce que M1 soit validé. La clé de session K n'est établie (i.e., considérée valide et utilisable) qu'après vérification réussie de M1. En cas d'échec, K' est rejetée et jamais retournée.

2.2 Flux détaillé loginVerify()¶

// auth.service.ts:199-245
async loginVerify(loginVerifyDto: LoginVerifyDto): Promise<{ accessToken: string; M2: string }> {
  // 1. Récupérer session SRP depuis Redis
  const session = await this.srpSessionStore.get(email);

  // 2. Vérifier TTL (double sécurité avec Redis)
  if (Date.now() - session.createdAt > TTL) → 401

  // 3. Vérifier preuve client (SrpService.verifyClientProof)
  //    - Calcul u, S, K
  //    - Vérification M1
  //    - Génération M2
  const { M2 } = this.srpService.verifyClientProof(...);

  // 4. Supprimer session (usage unique)
  await this.srpSessionStore.delete(email);

  // 5. Générer JWT
  const accessToken = this.jwtService.sign({ email, sub: userId });

  // 6. [À AJOUTER] Émettre événement audit

  return { accessToken, M2 };
}

2.3 Diagrammes Mermaid¶

2.3.1 Graphe de dépendances des composants¶

graph TD
    subgraph "API Layer"
        AC[AuthController<br/><code>auth.controller.ts</code>]
    end

    subgraph "Service Layer"
        AS[AuthService<br/><code>auth.service.ts</code>]
        SS[SrpService<br/><code>srp.service.ts</code>]
        JWT[JwtModule<br/><code>@nestjs/jwt</code>]
        AUD[AuditService<br/><code>audit.service.ts</code>]
    end

    subgraph "Data Layer"
        SSS[SrpSessionStoreService<br/><code>srp-session-store.service.ts</code>]
        REDIS[(Redis<br/>sessions SRP)]
        DB[(PostgreSQL<br/>users)]
    end

    subgraph "DTO"
        LVD[LoginVerifyDto<br/><code>login-verify.dto.ts</code>]
    end

    AC -->|"POST /auth/login/verify"| AS
    AC -.->|validation| LVD
    AS -->|"verifyClientProof()"| SS
    AS -->|"sign(payload)"| JWT
    AS -->|"log(event)"| AUD
    AS -->|"get/delete session"| SSS
    SSS -->|"GET/DEL srp:session:*"| REDIS
    AS -->|"findOne(email)"| DB

    style SS fill:#f9e6e6,stroke:#c0392b,color:#000
    style AUD fill:#e6f9e6,stroke:#27ae60,color:#000
    style REDIS fill:#e6e6f9,stroke:#2980b9,color:#000

2.3.2 Diagramme de séquence — Phase 2 (multi-service)¶

sequenceDiagram
    participant C as Client
    participant AC as AuthController
    participant AS as AuthService
    participant SSS as SrpSessionStoreService
    participant R as Redis
    participant SS as SrpService
    participant JWT as JwtModule
    participant AUD as AuditService

    C->>AC: POST /auth/login/verify { email, M1 }
    AC->>AS: loginVerify(loginVerifyDto)

    AS->>SSS: get(email)
    SSS->>R: GET srp:session:{email}
    R-->>SSS: { A, b, B, salt, verifier, createdAt }
    SSS-->>AS: session

    alt Session inexistante
        AS->>AUD: log(AUTH_SRP_VERIFY_FAILURE, SESSION_NOT_FOUND)
        AS-->>AC: throw 401
        AC-->>C: 401 Unauthorized
    end

    alt Session expirée (TTL > 5 min)
        AS->>SSS: delete(email)
        SSS->>R: DEL srp:session:{email}
        AS->>AUD: log(AUTH_SRP_VERIFY_FAILURE, SESSION_EXPIRED)
        AS-->>AC: throw 401
        AC-->>C: 401 Unauthorized
    end

    AS->>SS: verifyClientProof(salt, verifier, A, B, b, M1)
    Note over SS: 1. u = SHA3-256(A || B)<br/>2. S = (A * v^u)^b mod N<br/>3. K' = SHA3-256(S)<br/>4. M1' = SHA3-256(A||B||K')<br/>5. M1' === M1 ?

    alt M1 invalide
        SS-->>AS: throw Error("Preuve client invalide")
        AS->>SSS: delete(email)
        SSS->>R: DEL srp:session:{email}
        AS->>AUD: log(AUTH_SRP_VERIFY_FAILURE, Preuve invalide)
        AS-->>AC: throw 401
        AC-->>C: 401 Unauthorized
    end

    SS-->>AS: { M2 }
    Note over SS: K := K' (clé établie)<br/>M2 = SHA3-256(A||M1||K)

    AS->>SSS: delete(email)
    SSS->>R: DEL srp:session:{email}
    Note over SSS: Session usage unique

    AS->>JWT: sign({ email, sub: userId })
    JWT-->>AS: accessToken

    AS->>AUD: log(AUTH_SRP_VERIFY_SUCCESS)
    AS-->>AC: { accessToken, M2 }
    AC-->>C: 200 { accessToken, M2 }

    Note over C: Vérification M2<br/>(auth mutuelle)

3. Mapping invariants → mécanismes¶

3.1 Implémentation INV-7 (Traçabilité) — OBLIGATOIRE¶

Objectif : Tracer toutes les tentatives d'authentification SRP (succès et échecs).

Fichiers à modifier :

1. src/modules/auth/auth.module.ts — Importer AuditModule
2. src/modules/auth/auth.service.ts — Injecter et appeler AuditService

Étape 1 : Mise à jour du module

// auth.module.ts
import { AuditModule } from '../audit/audit.module';

@Module({
  imports: [
    // ... existant
    AuditModule,  // AJOUTER
  ],
  // ...
})
export class AuthModule {}

Étape 2 : Injection dans AuthService

// auth.service.ts - Constructeur
import { AuditService } from '../audit/audit.service';

constructor(
  private readonly jwtService: JwtService,
  private readonly srpService: SrpService,
  private readonly srpSessionStore: SrpSessionStoreService,
  private readonly auditService: AuditService,  // AJOUTER
  @InjectRepository(User)
  private readonly userRepository: Repository<User>,
) {}

Étape 3 : Implémentation complète de loginVerify avec audit

// auth.service.ts - Méthode loginVerify() complète
async loginVerify(loginVerifyDto: LoginVerifyDto): Promise<{ accessToken: string; M2: string }> {
  const { email, M1 } = loginVerifyDto;

  // 1. Récupérer session SRP
  const session = await this.srpSessionStore.get(email);
  if (!session) {
    // Audit : tentative sur session inexistante
    await this.auditService.log({
      action: 'AUTH_SRP_VERIFY_FAILURE',
      userId: null,
      metadata: { email, reason: 'SESSION_NOT_FOUND', timestamp: Date.now() },
    });
    throw new UnauthorizedException('Session SRP expirée ou invalide');
  }

  // 2. Vérifier TTL
  if (Date.now() - session.createdAt > this.srpSessionStore.getTtlMs()) {
    await this.srpSessionStore.delete(email);
    // Audit : session expirée
    await this.auditService.log({
      action: 'AUTH_SRP_VERIFY_FAILURE',
      userId: session.userId,
      metadata: { email, reason: 'SESSION_EXPIRED', timestamp: Date.now() },
    });
    throw new UnauthorizedException('Session SRP expirée');
  }

  try {
    // 3. Vérifier preuve client
    const { M2 } = this.srpService.verifyClientProof(
      session.salt, session.verifier, session.A, session.B, session.b, M1,
    );

    // 4. Supprimer session (usage unique)
    await this.srpSessionStore.delete(email);

    // 5. Générer JWT
    const payload = { email, sub: session.userId };
    const accessToken = this.jwtService.sign(payload);

    // 6. Audit : succès authentification
    await this.auditService.log({
      action: 'AUTH_SRP_VERIFY_SUCCESS',
      userId: session.userId,
      metadata: { email, timestamp: Date.now() },
    });

    return { accessToken, M2 };

  } catch (error) {
    // Nettoyage session
    await this.srpSessionStore.delete(email);

    // Audit : échec vérification
    await this.auditService.log({
      action: 'AUTH_SRP_VERIFY_FAILURE',
      userId: session.userId,
      metadata: {
        email,
        reason: error instanceof Error ? error.message : 'UNKNOWN_ERROR',
        timestamp: Date.now(),
      },
    });

    if (error instanceof Error && error.message.includes('Preuve client invalide')) {
      throw new UnauthorizedException('Identifiants invalides');
    }
    throw new InternalServerErrorException("Erreur lors de la vérification");
  }
}

Événements d'audit définis :

Raisons d'échec tracées : - SESSION_NOT_FOUND : Session SRP inexistante - SESSION_EXPIRED : Session SRP expirée (TTL dépassé) - Preuve client invalide : M1 incorrect - UNKNOWN_ERROR : Erreur interne

4. Gestion des erreurs¶

4.1 Matrice des erreurs¶

4.2 Code existant¶

// auth.service.ts:203-244
async loginVerify(...) {
  const session = await this.srpSessionStore.get(email);
  if (!session) {
    throw new UnauthorizedException('Session SRP expirée ou invalide');  // ✅
  }

  if (Date.now() - session.createdAt > TTL) {
    await this.srpSessionStore.delete(email);
    throw new UnauthorizedException('Session SRP expirée');  // ✅
  }

  try {
    const { M2 } = this.srpService.verifyClientProof(...);
    await this.srpSessionStore.delete(email);  // ✅ Usage unique
    // ...
  } catch (error) {
    await this.srpSessionStore.delete(email);  // ✅ Nettoyage sur erreur
    if (error.message.includes('Preuve client invalide')) {
      throw new UnauthorizedException('Identifiants invalides');  // ✅
    }
    throw new InternalServerErrorException(...);  // ✅
  }
}

4.3 Réponses non-informatives (sécurité)¶

Le serveur ne distingue pas publiquement : - Utilisateur inexistant vs preuve invalide → même message 401 - Session expirée vs inexistante → même message 401

Cela prévient les attaques par énumération.

5. Impacts sécurité¶

5.1 Analyse STRIDE¶

5.2 Conformité¶

5.3 Recommandations complémentaires¶

1. Rate limiting : Limiter à 5 tentatives/minute par IP
2. Monitoring : Alertes sur taux d'échec > 10%
3. Rotation JWT secret : Via Vault/KMS

6. Hypothèses techniques¶

7. Points de vigilance¶

7.1 Points critiques¶

7.2 Réponses aux points à clarifier (Spec §10)¶

7.3 Tests d'acceptance requis¶

# Scénario 1 — Authentification réussie
Given une session SRP valide avec A, b, B, salt, verifier
And une preuve client M1 correctement calculée
When POST /auth/login/verify { email, M1 }
Then response.status = 200
And response.body.accessToken est un JWT valide
And response.body.M2 permet au client de vérifier le serveur
And la session SRP est supprimée de Redis

# Scénario 2 — Preuve invalide
Given une session SRP valide
And une preuve client M1 incorrecte
When POST /auth/login/verify { email, M1 }
Then response.status = 401
And response.body.message = "Identifiants invalides"
And la session SRP est supprimée de Redis
And un événement audit "AUTH_SRP_VERIFY_FAILURE" est émis

# Scénario 3 — Session expirée
Given une session SRP créée il y a > 5 minutes
When POST /auth/login/verify { email, M1 }
Then response.status = 401
And response.body.message = "Session SRP expirée"

8. État actuel de l'implémentation¶

8.1 Éléments déjà implémentés (PD-24)¶

8.2 Éléments à implémenter (PD-25)¶

Note : L'intégration audit (INV-7) est obligatoire pour la conformité spec §4.7. Le code complet est fourni en §3.1.

Fin du plan d'implémentation PD-25.