PD-36 — Rétrospective¶

1. Contexte¶

2. Métriques¶

3. Learnings clés¶

• mTLS avec HSM = OpenSSL ENGINE API : Node.js ne permet pas de fournir une clé privée "opaque" pour TLS. L'API privateKeyEngine + privateKeyIdentifier (PKCS#11 URI RFC 7512) est la seule option viable.

• CloudHSM SDK 5 vs SDK 3 templates : Le SDK 5 dérive implicitement CKA_CLASS/CKA_KEY_TYPE du mécanisme. Ajouter ces attributs explicitement provoque CKR_ATTRIBUTE_VALUE_INVALID.

• Pool de sessions HSM indispensable : Pour éviter les timeouts sur applications long-running, le pattern acquire/release avec renouvellement avant expiration (marge 30s) est robuste.

• Validation fail-fast : Les erreurs de configuration HSM doivent être détectées au démarrage (OnModuleInit), pas à l'exécution d'une opération.

• API deprecated documentée : Documenter explicitement (NOSONAR + commentaires) les usages d'API deprecated avec justification et plan de migration.

4. Patterns applicables¶

Pattern existant : Chargement dynamique natif¶

// Évite erreurs de compilation native en CI/test sans CloudHSM
const pkcs11Module = await import('pkcs11js');
this.pkcs11 = new pkcs11Module.PKCS11();

Nouveau pattern : Pool de sessions HSM¶

class HsmSessionPool {
  private pool: Session[] = [];

  async acquire(): Promise<Session> {
    const session = this.pool.pop() ?? await this.createSession();
    if (this.isExpiringSoon(session)) {
      await session.renew();
    }
    return session;
  }

  release(session: Session): void {
    this.pool.push(session);
  }
}

Nouveau pattern : PKCS#11 URI (RFC 7512)¶

const pkcs11Uri = `pkcs11:token=${token};object=${label};type=private`;
const secureContextOptions: tls.SecureContextOptions = {
  cert: certBuffer,
  privateKeyEngine: 'cloudhsm',
  privateKeyIdentifier: pkcs11Uri,
};

5. Signal CLAUDE.md¶

Priorité moyenne : Documenter l'architecture HSM.

### HSM Cloud — Architecture standard (2026-02-XX)

L'intégration HSM Cloud suit le pattern :
1. **Provider PKCS#11** : Abstraction bas niveau (`cloudhsm-pkcs11.provider.ts`)
2. **Session Pool** : Gestion des sessions avec renouvellement
3. **Service HSM** : Facade exposant sign/verify/generateKey
4. **mTLS** : Via OpenSSL ENGINE API (deprecated mais seule option)

**URI PKCS#11** : `pkcs11:token=<token>;object=<label>;type=private`

6. Conclusion¶

PD-36 a livré un client HSM PKCS#11 complet avec signature, vérification, CSR et mTLS. Les 4 écarts (mTLS ENGINE, RSA support, session pool, fail-fast) ont tous été résolus. L'architecture Provider/Pool/Service est réutilisée par PD-37, PD-39 et PD-40.

Rétrospective générée 2026-02-19 (Étape 10 batch crypto-proof)